use flodl::Tensor;
use flodl::tensor::Result;
use crate::utils::tabular_data::Dataset;
use crate::utils::seed::derive_seed;
pub const EVAL_STREAM_OFFSET: u64 = 0xFFFF;
pub const EXAM_STREAM_OFFSET: u64 = 0xFFFF_FFFF;
#[derive(Clone, Debug)]
pub struct PoolSplit {
pub train: Vec<i64>,
pub eval: Vec<i64>,
pub gating: Vec<i64>,
}
impl PoolSplit {
pub fn new(len: usize, train_eval_split_ratio: f32, seed: u64) -> Self {
let (train, rest) = crate::utils::tabular_data::split_indices(
len,
1.0 - train_eval_split_ratio,
train_eval_split_ratio,
seed,
);
let half = rest.len() / 2;
let (eval, gating) = if half == 0 && rest.len() > 1 {
(rest[..rest.len() - 1].to_vec(), rest[rest.len() - 1..].to_vec())
} else if rest.len() == 1 {
(rest.clone(), rest.clone())
} else {
(rest[..half].to_vec(), rest[half..].to_vec())
};
PoolSplit { train, eval, gating }
}
pub fn of(dataset: &Dataset, train_eval_split_ratio: f32, seed: u64) -> Self {
Self::new(dataset.len(), train_eval_split_ratio, seed)
}
}
#[derive(Clone, Debug)]
pub struct BatchStream {
run_seed: u64,
batch_size: usize,
eval_batch_size: usize,
held_out_eval_rows: usize,
checkpoint_every: usize,
train_pool: Vec<i64>,
eval_pool: Vec<i64>,
gating_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,
held_out_eval_rows: 256, checkpoint_every: 100, train_pool: split.train,
eval_pool: split.eval,
gating_pool: split.gating,
}
}
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_held_out_eval_rows(mut self, n: usize) -> Self {
self.held_out_eval_rows = n.max(1);
self
}
pub fn with_checkpoint_every(mut self, n: usize) -> Self {
self.checkpoint_every = n.max(1);
self
}
pub fn set_checkpoint_every(&mut self, n: usize) {
self.checkpoint_every = n.max(1);
}
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 train_eval_split_ratio(&self) -> f32 {
self.train_pool.len() as f32 / (self.train_pool.len() + self.eval_pool.len()) as f32
}
pub fn held_out_eval_rows(&self) -> usize {
self.held_out_eval_rows
}
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)> {
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);
Self::gather(dataset, &Self::window(&perm, self.batch_size, offset))
}
pub fn eval_pool_rows(&self, n: usize) -> Result<Vec<i64>> {
self.eval_pool_rows_at(n, 0)
}
pub fn eval_pool_rows_at(&self, n: usize, era: u64) -> Result<Vec<i64>> {
let perm = self.eval_permutation(era);
Ok(Self::window(&perm, n.max(1), 0))
}
pub fn gather_rows(&self, dataset: &Dataset, indices: &[i64]) -> Result<(Tensor, Tensor)> {
Self::gather(dataset, indices)
}
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 {
(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))
}
pub fn exam_batch(&self, dataset: &Dataset, era: u64) -> Result<(Tensor, Tensor)> {
let exam_seed = derive_seed(
self.run_seed.wrapping_add(EXAM_STREAM_OFFSET),
era as usize,
);
let mut perm = self.gating_pool.clone();
let mut rng = fastrand::Rng::with_seed(exam_seed);
for i in (1..perm.len()).rev() {
let j = rng.usize(0..=i);
perm.swap(i, j);
}
let n = self.held_out_eval_rows.min(perm.len()).max(1);
Self::gather(dataset, &perm[..n])
}
}
#[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() + split.gating.len(),
ds.len()
);
let mut seen = split.train.clone();
seen.extend(split.eval.clone());
seen.extend(split.gating.clone());
seen.sort();
seen.dedup();
assert_eq!(seen.len(), ds.len(), "pools must not overlap");
}
#[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 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 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 gating_pool_is_disjoint_from_train_and_eval() {
let ds = small_dataset();
let split = PoolSplit::of(&ds, 0.25, 7);
let mut all: Vec<i64> = split
.train
.iter()
.chain(split.eval.iter())
.chain(split.gating.iter())
.copied()
.collect();
all.sort();
all.dedup();
assert_eq!(all.len(), ds.len(), "train+eval+gating must cover the dataset");
assert!(!split.gating.is_empty(), "gating pool must be non-empty");
}
#[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"
);
}
#[test]
fn exam_batch_is_deterministic_and_era_dependent() {
let ds = small_dataset();
let s = BatchStream::new(99, 8, PoolSplit::of(&ds, 0.25, 99));
let (e0x, e0y) = s.exam_batch(&ds, 0).unwrap();
let (e0_again, _) = s.exam_batch(&ds, 0).unwrap();
assert_eq!(
e0x.to_f32_vec().unwrap(),
e0_again.to_f32_vec().unwrap(),
"exam is a pure function of (run_seed, era)"
);
let (e1x, _) = s.exam_batch(&ds, 1).unwrap();
assert_ne!(
e0x.to_f32_vec().unwrap(),
e1x.to_f32_vec().unwrap(),
"each era gets a fresh exam"
);
assert_eq!(e0y.shape(), e0x.shape());
}
}