use crate::error::{BarracudaError, Result};
pub(crate) struct Xoshiro256 {
s: [u64; 4],
}
impl Xoshiro256 {
pub(crate) fn new(seed: u64) -> Self {
let mut z = seed;
let mut s = [0u64; 4];
for si in &mut s {
z = z.wrapping_add(0x9e37_79b9_7f4a_7c15);
z = (z ^ (z >> 30)).wrapping_mul(0xbf58_476d_1ce4_e5b9);
z = (z ^ (z >> 27)).wrapping_mul(0x94d0_49bb_1331_11eb);
*si = z ^ (z >> 31);
}
Self { s }
}
pub(crate) fn next_u64(&mut self) -> u64 {
let result = (self.s[1].wrapping_mul(5)).rotate_left(7).wrapping_mul(9);
let t = self.s[1] << 17;
self.s[2] ^= self.s[0];
self.s[3] ^= self.s[1];
self.s[1] ^= self.s[2];
self.s[0] ^= self.s[3];
self.s[2] ^= t;
self.s[3] = self.s[3].rotate_left(45);
result
}
pub(crate) fn next_f64(&mut self) -> f64 {
(self.next_u64() >> 11) as f64 / (1u64 << 53) as f64
}
fn shuffle(&mut self, slice: &mut [usize]) {
let n = slice.len();
for i in (1..n).rev() {
let j = (self.next_u64() as usize) % (i + 1);
slice.swap(i, j);
}
}
}
pub fn latin_hypercube(
n_samples: usize,
bounds: &[(f64, f64)],
seed: u64,
) -> Result<Vec<Vec<f64>>> {
if n_samples == 0 {
return Err(BarracudaError::InvalidInput {
message: "n_samples must be > 0".to_string(),
});
}
if bounds.is_empty() {
return Err(BarracudaError::InvalidInput {
message: "bounds must be non-empty".to_string(),
});
}
for (i, &(lo, hi)) in bounds.iter().enumerate() {
if lo >= hi {
return Err(BarracudaError::InvalidInput {
message: format!(
"Bounds for dimension {i} are invalid: [{lo}, {hi}] (lower >= upper)"
),
});
}
}
let n_dims = bounds.len();
let mut rng = Xoshiro256::new(seed);
let mut samples = vec![vec![0.0; n_dims]; n_samples];
for d in 0..n_dims {
let (lo, hi) = bounds[d];
let mut perm: Vec<usize> = (0..n_samples).collect();
rng.shuffle(&mut perm);
let interval_width = (hi - lo) / n_samples as f64;
for i in 0..n_samples {
let interval_idx = perm[i];
let interval_lo = (interval_idx as f64).mul_add(interval_width, lo);
let interval_hi = interval_lo + interval_width;
samples[i][d] = rng
.next_f64()
.mul_add(interval_hi - interval_lo, interval_lo);
}
}
Ok(samples)
}
#[must_use]
pub fn random_uniform(n_samples: usize, bounds: &[(f64, f64)], seed: u64) -> Vec<Vec<f64>> {
let n_dims = bounds.len();
let mut rng = Xoshiro256::new(seed);
(0..n_samples)
.map(|_| {
(0..n_dims)
.map(|d| {
let (lo, hi) = bounds[d];
rng.next_f64().mul_add(hi - lo, lo)
})
.collect()
})
.collect()
}
#[must_use]
pub fn maximin_distance(points: &[Vec<f64>]) -> f64 {
let n = points.len();
if n < 2 {
return f64::INFINITY;
}
let mut min_dist = f64::INFINITY;
for i in 0..n {
for j in (i + 1)..n {
let dist: f64 = points[i]
.iter()
.zip(points[j].iter())
.map(|(&a, &b)| (a - b).powi(2))
.sum::<f64>()
.sqrt();
if dist < min_dist {
min_dist = dist;
}
}
}
min_dist
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_lhs_basic_2d() {
let bounds = vec![(-5.0, 5.0), (-5.0, 5.0)];
let samples = latin_hypercube(10, &bounds, 42).unwrap();
assert_eq!(samples.len(), 10);
assert_eq!(samples[0].len(), 2);
for point in &samples {
assert!(point[0] >= -5.0 && point[0] <= 5.0);
assert!(point[1] >= -5.0 && point[1] <= 5.0);
}
}
#[test]
fn test_lhs_stratification() {
let bounds = vec![(0.0, 10.0)];
let samples = latin_hypercube(10, &bounds, 42).unwrap();
let mut intervals_used = [false; 10];
for point in &samples {
let interval = (point[0] as usize).min(9);
assert!(
!intervals_used[interval],
"Interval {interval} used more than once"
);
intervals_used[interval] = true;
}
assert!(intervals_used.iter().all(|&used| used));
}
#[test]
fn test_lhs_higher_dimensions() {
let bounds = vec![
(0.0, 1.0),
(-100.0, 100.0),
(0.0, 1e6),
(-1.0, 1.0),
(0.0, 0.001),
];
let samples = latin_hypercube(50, &bounds, 123).unwrap();
assert_eq!(samples.len(), 50);
assert_eq!(samples[0].len(), 5);
for point in &samples {
for (d, &val) in point.iter().enumerate() {
let (lo, hi) = bounds[d];
assert!(
val >= lo && val <= hi,
"Dim {d} value {val} outside [{lo}, {hi}]"
);
}
}
}
#[test]
fn test_lhs_reproducibility() {
let bounds = vec![(0.0, 1.0), (0.0, 1.0)];
let a = latin_hypercube(20, &bounds, 42).unwrap();
let b = latin_hypercube(20, &bounds, 42).unwrap();
for i in 0..20 {
assert_eq!(a[i][0], b[i][0]);
assert_eq!(a[i][1], b[i][1]);
}
}
#[test]
fn test_lhs_different_seeds() {
let bounds = vec![(0.0, 1.0), (0.0, 1.0)];
let a = latin_hypercube(20, &bounds, 42).unwrap();
let b = latin_hypercube(20, &bounds, 99).unwrap();
let different = a
.iter()
.zip(b.iter())
.any(|(ai, bi)| (ai[0] - bi[0]).abs() > 1e-15);
assert!(different);
}
#[test]
fn test_lhs_vs_random_coverage() {
let bounds = vec![(0.0, 1.0), (0.0, 1.0)];
let n_trials = 10;
let n_samples = 30;
let mut lhs_maximin_total = 0.0;
let mut rng_maximin_total = 0.0;
for trial in 0..n_trials {
let seed = trial as u64 * 1000 + 42;
let lhs_points = latin_hypercube(n_samples, &bounds, seed).unwrap();
let rng_points = random_uniform(n_samples, &bounds, seed + 1);
lhs_maximin_total += maximin_distance(&lhs_points);
rng_maximin_total += maximin_distance(&rng_points);
}
let lhs_avg = lhs_maximin_total / n_trials as f64;
let rng_avg = rng_maximin_total / n_trials as f64;
assert!(
lhs_avg > rng_avg * 0.9, "LHS avg maximin ({lhs_avg:.4}) should be >= random avg maximin ({rng_avg:.4})"
);
}
#[test]
fn test_lhs_errors() {
let bounds = vec![(0.0, 1.0)];
assert!(latin_hypercube(0, &bounds, 42).is_err());
assert!(latin_hypercube(10, &[], 42).is_err());
assert!(latin_hypercube(10, &[(5.0, 1.0)], 42).is_err());
assert!(latin_hypercube(10, &[(1.0, 1.0)], 42).is_err());
}
#[test]
fn test_lhs_single_sample() {
let bounds = vec![(0.0, 10.0), (-5.0, 5.0)];
let samples = latin_hypercube(1, &bounds, 42).unwrap();
assert_eq!(samples.len(), 1);
assert_eq!(samples[0].len(), 2);
assert!(samples[0][0] >= 0.0 && samples[0][0] <= 10.0);
assert!(samples[0][1] >= -5.0 && samples[0][1] <= 5.0);
}
#[test]
fn test_random_uniform_basic() {
let bounds = vec![(0.0, 1.0), (-1.0, 1.0)];
let samples = random_uniform(100, &bounds, 42);
assert_eq!(samples.len(), 100);
for point in &samples {
assert!(point[0] >= 0.0 && point[0] <= 1.0);
assert!(point[1] >= -1.0 && point[1] <= 1.0);
}
}
#[test]
fn test_maximin_distance_basic() {
let points = vec![
vec![0.0, 0.0],
vec![1.0, 0.0],
vec![0.0, 1.0],
vec![1.0, 1.0],
];
let dist = maximin_distance(&points);
assert!((dist - 1.0).abs() < 1e-10); }
#[test]
fn test_lhs_10d_nuclear_eos_bounds() {
let bounds = vec![
(-3000.0, -1000.0), (100.0, 800.0), (-800.0, 0.0), (8000.0, 20_000.0), (-1.0, 2.0), (-2.0, 1.0), (-2.0, 0.0), (0.0, 2.0), (0.05, 0.5), (50.0, 200.0), ];
let samples = latin_hypercube(1000, &bounds, 42).unwrap();
assert_eq!(samples.len(), 1000);
assert_eq!(samples[0].len(), 10);
for point in &samples {
for (d, &val) in point.iter().enumerate() {
let (lo, hi) = bounds[d];
assert!(val >= lo && val <= hi, "Dim {d} out of bounds");
}
}
}
}