use flodl::Tensor;
use flodl::tensor::Result;
use crate::utils::seed::derive_seed;
use crate::utils::tabular_data::Dataset;
pub const EVAL_STREAM_OFFSET: u64 = 0xFFFF;
fn seeded_split(len: usize, train_ratio: f32, eval_ratio: f32, seed: u64) -> (Vec<i64>, Vec<i64>) {
assert!(
(train_ratio + eval_ratio - 1.0).abs() < 1e-6,
"ratios must sum to 1.0"
);
let mut indices: Vec<i64> = (0..len as i64).collect();
let mut rng = fastrand::Rng::with_seed(seed);
for i in (1..indices.len()).rev() {
let j = rng.usize(0..=i);
indices.swap(i, j);
}
let split = (len as f32 * train_ratio).round() as usize;
let train: Vec<i64> = indices[..split].to_vec();
let eval: Vec<i64> = indices[split..].to_vec();
if eval.is_empty() {
static WARNED: std::sync::Once = std::sync::Once::new();
WARNED.call_once(|| {
tracing::warn!(
"eval set is empty (train_ratio={train_ratio}) — falling back to using ALL data for eval (train/eval overlap)"
);
});
(train, indices.clone())
} else {
(train, eval)
}
}
#[derive(Clone, Debug)]
pub struct PoolSplit {
pub train: Vec<i64>,
pub eval: Vec<i64>,
}
impl PoolSplit {
pub fn new(len: usize, train_eval_split_ratio: f32, seed: u64) -> Self {
let (train, eval) = seeded_split(
len,
1.0 - train_eval_split_ratio,
train_eval_split_ratio,
seed,
);
PoolSplit { train, eval }
}
pub fn of(dataset: &Dataset, train_eval_split_ratio: f32, seed: u64) -> Self {
Self::new(dataset.len(), train_eval_split_ratio, seed)
}
pub fn explicit(train_len: usize, test_len: usize, seed: u64) -> Self {
assert!(test_len > 0, "explicit split needs a non-empty test pool");
let train: Vec<i64> = (0..train_len as i64).collect();
let mut eval: Vec<i64> = (train_len as i64..(train_len + test_len) as i64).collect();
let mut rng = fastrand::Rng::with_seed(seed);
for i in (1..eval.len()).rev() {
let j = rng.usize(0..=i);
eval.swap(i, j);
}
PoolSplit { train, eval }
}
}
#[derive(Clone, Debug)]
pub struct BatchStream {
run_seed: u64,
batch_size: usize,
eval_batch_size: usize,
checkpoint_every: usize,
train_pool: Vec<i64>,
eval_pool: Vec<i64>,
}
impl BatchStream {
pub fn new(run_seed: u64, batch_size: usize, split: PoolSplit) -> Self {
BatchStream {
run_seed,
batch_size,
eval_batch_size: batch_size,
checkpoint_every: 100, train_pool: split.train,
eval_pool: split.eval,
}
}
pub fn with_eval_batch_size(mut self, eval_batch_size: usize) -> Self {
self.eval_batch_size = eval_batch_size.max(1);
self
}
pub fn with_checkpoint_every(mut self, n: usize) -> Self {
self.checkpoint_every = n;
self
}
pub fn set_run_checkpoint_every(&mut self, n: usize) {
self.checkpoint_every = n;
}
pub fn batch_size(&self) -> usize {
self.batch_size
}
pub fn checkpoint_every(&self) -> usize {
self.checkpoint_every
}
pub fn eval_batch_size(&self) -> usize {
self.eval_batch_size
}
pub fn pools(&self) -> (&[i64], &[i64]) {
(&self.train_pool, &self.eval_pool)
}
pub fn train_share(&self) -> f32 {
self.train_pool.len() as f32 / (self.train_pool.len() + self.eval_pool.len()) as f32
}
fn gather(dataset: &Dataset, indices: &[i64]) -> Result<(Tensor, Tensor)> {
let idx = Tensor::from_i64(indices, &[indices.len() as i64], dataset.inputs.device())?;
let x = dataset.inputs.index_select(0, &idx)?;
let y = dataset.targets.index_select(0, &idx)?;
Ok((x, y))
}
fn window(pool: &[i64], batch_size: usize, offset: usize) -> Vec<i64> {
let n = pool.len();
(0..batch_size).map(|i| pool[(offset + i) % n]).collect()
}
pub fn train_batch(&self, dataset: &Dataset, step: u64) -> Result<(Tensor, Tensor)> {
self.train_batch_at(dataset, step, 0)
}
pub fn train_batch_at(
&self,
dataset: &Dataset,
step: u64,
attempt: u64,
) -> Result<(Tensor, Tensor)> {
let perm_seed = derive_seed(self.run_seed, 0);
let mut perm = self.train_pool.clone();
let mut rng = fastrand::Rng::with_seed(perm_seed);
for i in (1..perm.len()).rev() {
let j = rng.usize(0..=i);
perm.swap(i, j);
}
let offset = (step as usize)
.wrapping_mul(self.batch_size)
.wrapping_add((attempt as usize).wrapping_mul(self.batch_size));
Self::gather(dataset, &Self::window(&perm, self.batch_size, offset))
}
fn eval_permutation(&self, era: u64) -> Vec<i64> {
let perm_seed = derive_seed(self.run_seed.wrapping_add(EVAL_STREAM_OFFSET), era as usize);
let mut perm = self.eval_pool.clone();
let mut rng = fastrand::Rng::with_seed(perm_seed);
for i in (1..perm.len()).rev() {
let j = rng.usize(0..=i);
perm.swap(i, j);
}
perm
}
fn era_of(&self, step: u64) -> u64 {
if self.checkpoint_every == 0 {
return 0;
}
(step as usize / self.checkpoint_every) as u64
}
pub fn eval_batch(&self, dataset: &Dataset, step: u64) -> Result<(Tensor, Tensor)> {
let perm = self.eval_permutation(self.era_of(step));
let offset = (step as usize).wrapping_mul(self.eval_batch_size);
Self::gather(dataset, &Self::window(&perm, self.eval_batch_size, offset))
}
}
#[cfg(test)]
mod tests {
use super::*;
use flodl::Device;
fn small_dataset() -> Dataset {
crate::utils::tabular_data::synthetic_classification(64, 2, 2, 7, Device::CPU).unwrap()
}
#[test]
fn pool_split_is_disjoint_and_covering() {
let ds = small_dataset();
let split = PoolSplit::of(&ds, 0.25, 42);
assert_eq!(split.train.len() + split.eval.len(), ds.len());
let mut seen = split.train.clone();
seen.extend(split.eval.clone());
seen.sort();
seen.dedup();
assert_eq!(seen.len(), ds.len(), "pools must not overlap");
assert_eq!(split.eval.len(), ds.len() - split.train.len());
}
#[test]
fn pool_split_is_deterministic() {
let a = PoolSplit::new(100, 0.2, 123);
let b = PoolSplit::new(100, 0.2, 123);
let c = PoolSplit::new(100, 0.2, 124);
assert_eq!(a.train, b.train);
assert_eq!(a.eval, b.eval);
assert_ne!(a.train, c.train, "different seed ⇒ different split");
}
#[test]
fn explicit_split_separates_layouts_by_construction() {
let split = PoolSplit::explicit(80, 20, 42);
assert_eq!(
split.train,
(0..80).collect::<Vec<i64>>(),
"every train row is a training row"
);
let mut held: Vec<i64> = split.eval.clone();
held.sort();
assert_eq!(held, (80..100).collect::<Vec<i64>>());
let again = PoolSplit::explicit(80, 20, 42);
assert_eq!(split.eval, again.eval);
let other = PoolSplit::explicit(80, 20, 43);
assert_ne!(split.eval, other.eval, "seed re-shuffles the test pool");
let mut other_held: Vec<i64> = other.eval.clone();
other_held.sort();
assert_eq!(other_held, (80..100).collect::<Vec<i64>>());
}
#[test]
#[should_panic(expected = "non-empty test pool")]
fn explicit_split_rejects_empty_test_pool() {
let _ = PoolSplit::explicit(80, 0, 42);
}
#[test]
fn stream_batch_is_pure_function_of_seed_and_step() {
let ds = small_dataset();
let mk = |seed| BatchStream::new(seed, 8, PoolSplit::of(&ds, 0.25, seed));
let s = mk(99);
let (x1, y1) = s.train_batch(&ds, 5).unwrap();
let (x2, y2) = s.train_batch(&ds, 5).unwrap();
assert_eq!(x1.to_f32_vec().unwrap(), x2.to_f32_vec().unwrap());
assert_eq!(y1.to_f32_vec().unwrap(), y2.to_f32_vec().unwrap());
let (x3, _) = mk(99).train_batch(&ds, 5).unwrap();
assert_eq!(x1.to_f32_vec().unwrap(), x3.to_f32_vec().unwrap());
let (x4, _) = s.train_batch(&ds, 6).unwrap();
assert_ne!(x1.to_f32_vec().unwrap(), x4.to_f32_vec().unwrap());
let (x5, _) = mk(100).train_batch(&ds, 5).unwrap();
assert_ne!(x1.to_f32_vec().unwrap(), x5.to_f32_vec().unwrap());
}
#[test]
fn eval_stream_is_independent_of_train_stream() {
let ds = small_dataset();
let s = BatchStream::new(99, 8, PoolSplit::of(&ds, 0.25, 99));
let (tx, _) = s.train_batch(&ds, 0).unwrap();
let (ex, _) = s.eval_batch(&ds, 0).unwrap();
assert_ne!(tx.to_f32_vec().unwrap(), ex.to_f32_vec().unwrap());
}
#[test]
fn retry_attempt_walks_the_next_batch() {
let ds = small_dataset();
let s = BatchStream::new(99, 8, PoolSplit::of(&ds, 0.25, 99));
let (own, _) = s.train_batch(&ds, 5).unwrap();
let (zero, _) = s.train_batch_at(&ds, 5, 0).unwrap();
assert_eq!(
own.to_f32_vec().unwrap(),
zero.to_f32_vec().unwrap(),
"attempt 0 IS the clock's own draw"
);
let (first, _) = s.train_batch_at(&ds, 5, 1).unwrap();
assert_ne!(
own.to_f32_vec().unwrap(),
first.to_f32_vec().unwrap(),
"a retry on a fresh draw trains different rows"
);
assert_eq!(
first.to_f32_vec().unwrap(),
s.train_batch_at(&ds, 5, 1).unwrap().0.to_f32_vec().unwrap(),
"pure function of (seed, step, attempt) — a replay asks again"
);
}
#[test]
fn stream_wraps_around_pool() {
let ds = small_dataset();
let s = BatchStream::new(99, 8, PoolSplit::of(&ds, 0.25, 99));
let (x0, _) = s.train_batch(&ds, 0).unwrap();
let (x6, _) = s.train_batch(&ds, 6).unwrap();
assert_eq!(
x0.to_f32_vec().unwrap(),
x6.to_f32_vec().unwrap(),
"step 6 wraps to the lap-1 start"
);
}
#[test]
fn zero_cadence_freezes_the_eval_permutation() {
let ds = small_dataset();
let s = BatchStream::new(7, 8, PoolSplit::of(&ds, 0.25, 7))
.with_eval_batch_size(4)
.with_checkpoint_every(0);
assert_eq!(s.checkpoint_every(), 0);
for step in [0u64, 1, 5, 4096] {
let perm = s.eval_permutation(s.era_of(step));
let frozen = s.eval_permutation(0);
assert_eq!(perm, frozen, "step {step} must stay in the eternal era 0");
}
assert_eq!(
s.eval_batch(&ds, 3).unwrap().0.to_f32_vec().unwrap(),
s.eval_batch(&ds, 3).unwrap().0.to_f32_vec().unwrap()
);
let rotating = BatchStream::new(7, 8, PoolSplit::of(&ds, 0.25, 7))
.with_eval_batch_size(4)
.with_checkpoint_every(1);
assert_ne!(
rotating.eval_permutation(rotating.era_of(0)),
rotating.eval_permutation(rotating.era_of(1))
);
}
#[test]
fn eval_permutation_rotates_per_era() {
let ds = small_dataset();
let s = BatchStream::new(99, 8, PoolSplit::of(&ds, 0.25, 99))
.with_eval_batch_size(4)
.with_checkpoint_every(3);
let (a0, _) = s.eval_batch(&ds, 0).unwrap();
let (a1, _) = s.eval_batch(&ds, 1).unwrap();
assert_ne!(
a0.to_f32_vec().unwrap(),
a1.to_f32_vec().unwrap(),
"two steps in era 0 walk the same permutation"
);
let (b0, _) = s.eval_batch(&ds, 3).unwrap();
let (b0_again, _) = s.eval_batch(&ds, 3).unwrap();
assert_eq!(
b0.to_f32_vec().unwrap(),
b0_again.to_f32_vec().unwrap(),
"pure function of (run_seed, step)"
);
let era0_rows = (0..4usize)
.map(|i| s.eval_batch(&ds, i as u64).unwrap().0.to_f32_vec().unwrap())
.collect::<Vec<_>>()
.concat();
let era1_rows = (3..7usize)
.map(|i| s.eval_batch(&ds, i as u64).unwrap().0.to_f32_vec().unwrap())
.collect::<Vec<_>>()
.concat();
assert_ne!(
era0_rows, era1_rows,
"eval permutation must rotate across the era boundary"
);
}
}