Skip to main content

rusttorch_data/
collate.rs

1use std::{
2    collections::{BTreeMap, TryReserveError},
3    convert::Infallible,
4    error::Error,
5    fmt,
6};
7
8use rusttorch_core::{Result, RustTorchError, Tensor};
9
10use crate::Checkpointable;
11
12/// Converts an owned group of samples into one batch.
13///
14/// See [`DefaultCollator`], [`DefaultConverter`], [`FnCollate`], and
15/// [`VecCollate`] for compiling examples of the built-in implementations.
16pub trait Collate<Sample> {
17    /// Batch produced from the samples.
18    type Batch;
19
20    /// Error returned when collation fails.
21    type Error;
22
23    /// Collates `samples` into one batch.
24    fn collate(&mut self, samples: Vec<Sample>) -> std::result::Result<Self::Batch, Self::Error>;
25}
26
27/// Moves samples unchanged into their existing vector.
28///
29/// # Examples
30///
31/// ```
32/// use rusttorch_data::{Collate, VecCollate};
33///
34/// let mut collator = VecCollate;
35/// let batch = collator
36///     .collate(vec![String::from("first"), String::from("second")])
37///     .expect("VecCollate is infallible");
38/// assert_eq!(batch, ["first", "second"]);
39/// ```
40#[derive(Clone, Copy, Debug, Default)]
41pub struct VecCollate;
42
43impl Checkpointable for VecCollate {
44    type State = ();
45
46    fn save_state(&self) -> Self::State {}
47
48    fn validate_state(&self, _state: &Self::State) -> Result<()> {
49        Ok(())
50    }
51
52    fn load_validated(&mut self, _state: &Self::State) {}
53}
54
55impl<Sample> Collate<Sample> for VecCollate {
56    type Batch = Vec<Sample>;
57    type Error = Infallible;
58
59    fn collate(&mut self, samples: Vec<Sample>) -> std::result::Result<Self::Batch, Self::Error> {
60        Ok(samples)
61    }
62}
63
64/// Adapts an ordinary fallible closure to [`Collate`].
65///
66/// # Examples
67///
68/// ```
69/// use std::convert::Infallible;
70/// use rusttorch_data::{Collate, FnCollate};
71///
72/// # fn main() -> Result<(), Infallible> {
73/// let mut collator = FnCollate::new(|samples: Vec<Vec<i64>>| {
74///     Ok::<_, Infallible>(samples.into_iter().flatten().collect::<Vec<_>>())
75/// });
76/// assert_eq!(collator.collate(vec![vec![1, 2], vec![3]])?, [1, 2, 3]);
77/// # Ok(())
78/// # }
79/// ```
80#[derive(Clone, Copy, Debug)]
81pub struct FnCollate<F> {
82    collate: F,
83}
84
85impl<F> FnCollate<F> {
86    /// Creates a collator backed by `collate`.
87    pub fn new(collate: F) -> Self {
88        Self { collate }
89    }
90}
91
92impl<Sample, Batch, E, F> Collate<Sample> for FnCollate<F>
93where
94    F: FnMut(Vec<Sample>) -> std::result::Result<Batch, E>,
95{
96    type Batch = Batch;
97    type Error = E;
98
99    fn collate(&mut self, samples: Vec<Sample>) -> std::result::Result<Self::Batch, Self::Error> {
100        (self.collate)(samples)
101    }
102}
103
104/// A byte-string record that is not treated as a recursive numeric sequence.
105///
106/// `Vec<u8>` remains available for equal-length sequence collation. Wrap a
107/// byte string in `Bytes` when each sample must remain one byte record.
108///
109/// # Examples
110///
111/// ```
112/// use rusttorch_data::{Bytes, Collate, DefaultCollator};
113///
114/// let mut collator = DefaultCollator;
115/// let records = collator
116///     .collate(vec![Bytes(vec![1, 2]), Bytes(vec![3])])
117///     .expect("byte records collate");
118/// assert_eq!(records, [Bytes(vec![1, 2]), Bytes(vec![3])]);
119/// ```
120#[derive(Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
121pub struct Bytes(pub Vec<u8>);
122
123/// An error produced by built-in collation or conversion.
124///
125/// The [`DefaultCollator`] and [`DefaultConverter`] examples show the public
126/// operations that return this error.
127#[derive(Debug)]
128#[non_exhaustive]
129pub enum CollateError {
130    /// A collator received no top-level samples.
131    EmptyBatch,
132    /// A no-batching converter received other than one sample.
133    ConversionBatchSize {
134        /// Number of samples received.
135        actual: usize,
136    },
137    /// One sequence had a different length from the first sample.
138    SequenceLengthMismatch {
139        /// Zero-based sample position containing the mismatch.
140        sample: usize,
141        /// Length of the first sequence.
142        expected: usize,
143        /// Length of the mismatched sequence.
144        actual: usize,
145    },
146    /// One option had different presence from the first sample.
147    OptionPresenceMismatch {
148        /// Zero-based sample position containing the mismatch.
149        sample: usize,
150        /// Whether the first option was present.
151        expected_some: bool,
152        /// Whether the mismatched option was present.
153        actual_some: bool,
154    },
155    /// One map had a different ordered key set from the first sample.
156    MapKeysMismatch {
157        /// Zero-based sample position containing the mismatch.
158        sample: usize,
159    },
160    /// A caller-controlled size cannot be represented by the native API.
161    SizeOverflow {
162        /// Operation whose size was not representable.
163        context: &'static str,
164        /// Size supplied by the caller.
165        value: usize,
166    },
167    /// A required intermediate allocation could not be reserved.
168    Allocation {
169        /// Structure whose allocation failed.
170        context: &'static str,
171        /// Number of additional elements requested.
172        requested: usize,
173        /// Standard-library allocation error.
174        source: TryReserveError,
175    },
176    /// LibTorch rejected tensor construction or stacking.
177    LibTorch {
178        /// Preserved backend error and source chain.
179        source: RustTorchError,
180    },
181}
182
183impl fmt::Display for CollateError {
184    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
185        match self {
186            Self::EmptyBatch => formatter.write_str("cannot collate an empty batch"),
187            Self::ConversionBatchSize { actual } => write!(
188                formatter,
189                "default conversion requires exactly one sample, got {actual}"
190            ),
191            Self::SequenceLengthMismatch {
192                sample,
193                expected,
194                actual,
195            } => write!(
196                formatter,
197                "sequence sample {sample} has length {actual}, expected {expected}"
198            ),
199            Self::OptionPresenceMismatch {
200                sample,
201                expected_some,
202                actual_some,
203            } => write!(
204                formatter,
205                "option sample {sample} presence is {actual_some}, expected {expected_some}"
206            ),
207            Self::MapKeysMismatch { sample } => {
208                write!(formatter, "map sample {sample} has a different key set")
209            }
210            Self::SizeOverflow { context, value } => {
211                write!(formatter, "{context} size {value} is not representable")
212            }
213            Self::Allocation {
214                context,
215                requested,
216                source,
217            } => write!(
218                formatter,
219                "failed to reserve {requested} elements for {context}: {source}"
220            ),
221            Self::LibTorch { source } => write!(formatter, "LibTorch collation failed: {source}"),
222        }
223    }
224}
225
226impl Error for CollateError {
227    fn source(&self) -> Option<&(dyn Error + 'static)> {
228        match self {
229            Self::Allocation { source, .. } => Some(source),
230            Self::LibTorch { source } => Some(source),
231            _ => None,
232        }
233    }
234}
235
236impl From<Infallible> for CollateError {
237    fn from(error: Infallible) -> Self {
238        match error {}
239    }
240}
241
242fn reserve_vec<T>(
243    capacity: usize,
244    context: &'static str,
245) -> std::result::Result<Vec<T>, CollateError> {
246    let mut values = Vec::new();
247    values
248        .try_reserve_exact(capacity)
249        .map_err(|source| CollateError::Allocation {
250            context,
251            requested: capacity,
252            source,
253        })?;
254    Ok(values)
255}
256
257fn require_nonempty<T>(samples: &[T]) -> std::result::Result<(), CollateError> {
258    if samples.is_empty() {
259        Err(CollateError::EmptyBatch)
260    } else {
261        Ok(())
262    }
263}
264
265fn backend_error(source: impl Into<RustTorchError>) -> CollateError {
266    CollateError::LibTorch {
267        source: source.into(),
268    }
269}
270
271/// Recursively converts one Rust sample type into its default batch type.
272///
273/// Tensor samples stack on dimension zero. Scalar kinds are `u8` → `Uint8`,
274/// `i8` → `Int8`, `i16` → `Int16`, `i32` → `Int`, `i64` → `Int64`, `f32` →
275/// `Float`, `f64` → `Double`, and `bool` → `Bool`. Strings and [`Bytes`]
276/// remain records. Options, equal-length vectors, tuples of arity two through
277/// eight, and `BTreeMap` values recurse through this trait.
278///
279/// Use this trait through [`DefaultCollator`], whose example demonstrates
280/// numeric, Tensor, and typed recursive output.
281pub trait DefaultCollate: Sized {
282    /// Batch produced from a vector of this sample type.
283    type Batch;
284
285    /// Applies built-in typed collation.
286    fn default_collate(samples: Vec<Self>) -> std::result::Result<Self::Batch, CollateError>;
287}
288
289/// Applies [`DefaultCollate`] to an owned group of samples.
290///
291/// # Examples
292///
293/// ```
294/// use rusttorch_core::{Kind, Tensor};
295/// use rusttorch_data::{Bytes, Collate, CollateError, DefaultCollator};
296///
297/// # fn main() -> Result<(), CollateError> {
298/// let mut collator = DefaultCollator;
299/// let numbers: Tensor = collator.collate(vec![1_i64, 2])?;
300/// assert_eq!(numbers.kind(), Kind::Int64);
301/// assert_eq!(numbers.size(), [2]);
302///
303/// let tensors = collator.collate(vec![
304///     Tensor::from_slice(&[1_i64, 2]),
305///     Tensor::from_slice(&[3_i64, 4]),
306/// ])?;
307/// assert_eq!(tensors.size(), [2, 2]);
308///
309/// let nested: (Tensor, Vec<Bytes>) = collator.collate(vec![
310///     (1_i64, Bytes(vec![1, 2])),
311///     (2_i64, Bytes(vec![3])),
312/// ])?;
313/// assert_eq!(nested.0.size(), [2]);
314/// assert_eq!(nested.1, [Bytes(vec![1, 2]), Bytes(vec![3])]);
315/// # Ok(())
316/// # }
317/// ```
318#[derive(Clone, Copy, Debug, Default)]
319pub struct DefaultCollator;
320
321impl Checkpointable for DefaultCollator {
322    type State = ();
323
324    fn save_state(&self) -> Self::State {}
325
326    fn validate_state(&self, _state: &Self::State) -> Result<()> {
327        Ok(())
328    }
329
330    fn load_validated(&mut self, _state: &Self::State) {}
331}
332
333impl<Sample> Collate<Sample> for DefaultCollator
334where
335    Sample: DefaultCollate,
336{
337    type Batch = Sample::Batch;
338    type Error = CollateError;
339
340    fn collate(&mut self, samples: Vec<Sample>) -> std::result::Result<Self::Batch, Self::Error> {
341        Sample::default_collate(samples)
342    }
343}
344
345impl DefaultCollate for Tensor {
346    type Batch = Tensor;
347
348    fn default_collate(samples: Vec<Self>) -> std::result::Result<Self::Batch, CollateError> {
349        require_nonempty(&samples)?;
350        i32::try_from(samples.len()).map_err(|_| CollateError::SizeOverflow {
351            context: "tensor stack",
352            value: samples.len(),
353        })?;
354        Tensor::f_stack(&samples, 0).map_err(backend_error)
355    }
356}
357
358macro_rules! impl_numeric_collate {
359    ($($type:ty),+ $(,)?) => {
360        $(
361            impl DefaultCollate for $type {
362                type Batch = Tensor;
363
364                fn default_collate(
365                    samples: Vec<Self>,
366                ) -> std::result::Result<Self::Batch, CollateError> {
367                    require_nonempty(&samples)?;
368                    i64::try_from(samples.len()).map_err(|_| CollateError::SizeOverflow {
369                        context: "numeric tensor",
370                        value: samples.len(),
371                    })?;
372                    Tensor::f_from_slice(&samples).map_err(backend_error)
373                }
374            }
375        )+
376    };
377}
378
379impl_numeric_collate!(u8, i8, i16, i32, i64, f32, f64, bool);
380
381impl DefaultCollate for String {
382    type Batch = Vec<String>;
383
384    fn default_collate(samples: Vec<Self>) -> std::result::Result<Self::Batch, CollateError> {
385        require_nonempty(&samples)?;
386        Ok(samples)
387    }
388}
389
390impl DefaultCollate for Bytes {
391    type Batch = Vec<Bytes>;
392
393    fn default_collate(samples: Vec<Self>) -> std::result::Result<Self::Batch, CollateError> {
394        require_nonempty(&samples)?;
395        Ok(samples)
396    }
397}
398
399impl<T> DefaultCollate for Option<T>
400where
401    T: DefaultCollate,
402{
403    type Batch = Option<T::Batch>;
404
405    fn default_collate(samples: Vec<Self>) -> std::result::Result<Self::Batch, CollateError> {
406        require_nonempty(&samples)?;
407        let expected_some = samples[0].is_some();
408        for (sample, value) in samples.iter().enumerate().skip(1) {
409            let actual_some = value.is_some();
410            if actual_some != expected_some {
411                return Err(CollateError::OptionPresenceMismatch {
412                    sample,
413                    expected_some,
414                    actual_some,
415                });
416            }
417        }
418        if !expected_some {
419            return Ok(None);
420        }
421
422        let sample_count = samples.len();
423        let mut present = reserve_vec(sample_count, "option values")?;
424        for value in samples {
425            match value {
426                Some(value) => present.push(value),
427                None => {
428                    return Err(CollateError::OptionPresenceMismatch {
429                        sample: present.len(),
430                        expected_some: true,
431                        actual_some: false,
432                    });
433                }
434            }
435        }
436        T::default_collate(present).map(Some)
437    }
438}
439
440impl<T> DefaultCollate for Vec<T>
441where
442    T: DefaultCollate,
443{
444    type Batch = Vec<T::Batch>;
445
446    fn default_collate(samples: Vec<Self>) -> std::result::Result<Self::Batch, CollateError> {
447        require_nonempty(&samples)?;
448        let sequence_len = samples[0].len();
449        for (sample, sequence) in samples.iter().enumerate().skip(1) {
450            if sequence.len() != sequence_len {
451                return Err(CollateError::SequenceLengthMismatch {
452                    sample,
453                    expected: sequence_len,
454                    actual: sequence.len(),
455                });
456            }
457        }
458
459        let sample_count = samples.len();
460        let mut columns = reserve_vec(sequence_len, "sequence columns")?;
461        for _ in 0..sequence_len {
462            columns.push(reserve_vec(sample_count, "sequence column values")?);
463        }
464        for sequence in samples {
465            for (column, value) in columns.iter_mut().zip(sequence) {
466                column.push(value);
467            }
468        }
469
470        let mut batch = reserve_vec(sequence_len, "collated sequence")?;
471        for column in columns {
472            batch.push(T::default_collate(column)?);
473        }
474        Ok(batch)
475    }
476}
477
478impl<K, V> DefaultCollate for BTreeMap<K, V>
479where
480    K: Ord,
481    V: DefaultCollate,
482{
483    type Batch = BTreeMap<K, V::Batch>;
484
485    fn default_collate(samples: Vec<Self>) -> std::result::Result<Self::Batch, CollateError> {
486        require_nonempty(&samples)?;
487        for (sample, map) in samples.iter().enumerate().skip(1) {
488            if !samples[0].keys().eq(map.keys()) {
489                return Err(CollateError::MapKeysMismatch { sample });
490            }
491        }
492
493        let sample_count = samples.len();
494        let mut maps = samples.into_iter();
495        let first = maps.next().ok_or(CollateError::EmptyBatch)?;
496        let mut columns = BTreeMap::new();
497        for (key, value) in first {
498            let mut values = reserve_vec(sample_count, "map values")?;
499            values.push(value);
500            columns.insert(key, values);
501        }
502        for map in maps {
503            for (values, value) in columns.values_mut().zip(map.into_values()) {
504                values.push(value);
505            }
506        }
507
508        let mut batch = BTreeMap::new();
509        for (key, values) in columns {
510            batch.insert(key, V::default_collate(values)?);
511        }
512        Ok(batch)
513    }
514}
515
516/// Recursively converts one sample without adding a batch dimension.
517///
518/// Tensors, supported scalar primitives, strings, and [`Bytes`] are preserved.
519/// Options, vectors, tuples of arity two through eight, and `BTreeMap` values
520/// are converted recursively. Unlike [`DefaultCollate`], vectors are not
521/// transposed.
522///
523/// Use this trait through [`DefaultConverter`], whose example demonstrates
524/// recursive conversion without automatic batching.
525pub trait DefaultConvert: Sized {
526    /// Output produced from this sample type.
527    type Output;
528
529    /// Applies built-in conversion without automatic batching.
530    fn default_convert(self) -> std::result::Result<Self::Output, CollateError>;
531}
532
533/// Applies [`DefaultConvert`] in no-auto-batching mode.
534///
535/// # Examples
536///
537/// ```
538/// use rusttorch_data::{Bytes, Collate, CollateError, DefaultConverter};
539///
540/// # fn main() -> Result<(), CollateError> {
541/// let mut converter = DefaultConverter;
542/// assert_eq!(converter.convert(vec![1_i64, 2])?, [1, 2]);
543/// assert_eq!(
544///     converter.convert(Some(Bytes(vec![3, 4])))?,
545///     Some(Bytes(vec![3, 4])),
546/// );
547///
548/// // The `Collate` adapter accepts the loader's one-sample no-batch group.
549/// assert_eq!(converter.collate(vec![vec![5_i64, 6]])?, [5, 6]);
550/// # Ok(())
551/// # }
552/// ```
553#[derive(Clone, Copy, Debug, Default)]
554pub struct DefaultConverter;
555
556impl Checkpointable for DefaultConverter {
557    type State = ();
558
559    fn save_state(&self) -> Self::State {}
560
561    fn validate_state(&self, _state: &Self::State) -> Result<()> {
562        Ok(())
563    }
564
565    fn load_validated(&mut self, _state: &Self::State) {}
566}
567
568impl DefaultConverter {
569    /// Converts one sample without adding a batch dimension.
570    pub fn convert<T>(&mut self, sample: T) -> std::result::Result<T::Output, CollateError>
571    where
572        T: DefaultConvert,
573    {
574        sample.default_convert()
575    }
576}
577
578impl<Sample> Collate<Sample> for DefaultConverter
579where
580    Sample: DefaultConvert,
581{
582    type Batch = Sample::Output;
583    type Error = CollateError;
584
585    fn collate(&mut self, samples: Vec<Sample>) -> std::result::Result<Self::Batch, Self::Error> {
586        let actual = samples.len();
587        if actual != 1 {
588            return Err(CollateError::ConversionBatchSize { actual });
589        }
590        match samples.into_iter().next() {
591            Some(sample) => sample.default_convert(),
592            None => Err(CollateError::ConversionBatchSize { actual: 0 }),
593        }
594    }
595}
596
597macro_rules! impl_leaf_convert {
598    ($($type:ty),+ $(,)?) => {
599        $(
600            impl DefaultConvert for $type {
601                type Output = Self;
602
603                fn default_convert(self) -> std::result::Result<Self::Output, CollateError> {
604                    Ok(self)
605                }
606            }
607        )+
608    };
609}
610
611impl_leaf_convert!(Tensor, u8, i8, i16, i32, i64, f32, f64, bool, String, Bytes);
612
613impl<T> DefaultConvert for Option<T>
614where
615    T: DefaultConvert,
616{
617    type Output = Option<T::Output>;
618
619    fn default_convert(self) -> std::result::Result<Self::Output, CollateError> {
620        self.map(DefaultConvert::default_convert).transpose()
621    }
622}
623
624impl<T> DefaultConvert for Vec<T>
625where
626    T: DefaultConvert,
627{
628    type Output = Vec<T::Output>;
629
630    fn default_convert(self) -> std::result::Result<Self::Output, CollateError> {
631        let mut output = reserve_vec(self.len(), "converted sequence")?;
632        for value in self {
633            output.push(value.default_convert()?);
634        }
635        Ok(output)
636    }
637}
638
639impl<K, V> DefaultConvert for BTreeMap<K, V>
640where
641    K: Ord,
642    V: DefaultConvert,
643{
644    type Output = BTreeMap<K, V::Output>;
645
646    fn default_convert(self) -> std::result::Result<Self::Output, CollateError> {
647        let mut output = BTreeMap::new();
648        for (key, value) in self {
649            output.insert(key, value.default_convert()?);
650        }
651        Ok(output)
652    }
653}
654
655macro_rules! impl_tuple {
656    ($(($type:ident, $index:tt, $value:ident)),+ $(,)?) => {
657        impl<$($type),+> DefaultCollate for ($($type,)+)
658        where
659            $($type: DefaultCollate),+
660        {
661            type Batch = ($($type::Batch,)+);
662
663            fn default_collate(
664                samples: Vec<Self>,
665            ) -> std::result::Result<Self::Batch, CollateError> {
666                require_nonempty(&samples)?;
667                let sample_count = samples.len();
668                let mut fields = ($(reserve_vec::<$type>(sample_count, "tuple field")?,)+);
669                for ($($value,)+) in samples {
670                    $(fields.$index.push($value);)+
671                }
672                Ok(($($type::default_collate(fields.$index)?,)+))
673            }
674        }
675
676        impl<$($type),+> DefaultConvert for ($($type,)+)
677        where
678            $($type: DefaultConvert),+
679        {
680            type Output = ($($type::Output,)+);
681
682            fn default_convert(self) -> std::result::Result<Self::Output, CollateError> {
683                let ($($value,)+) = self;
684                Ok(($($value.default_convert()?,)+))
685            }
686        }
687    };
688}
689
690impl_tuple!((A, 0, a), (B, 1, b));
691impl_tuple!((A, 0, a), (B, 1, b), (C, 2, c));
692impl_tuple!((A, 0, a), (B, 1, b), (C, 2, c), (D, 3, d));
693impl_tuple!((A, 0, a), (B, 1, b), (C, 2, c), (D, 3, d), (E, 4, e));
694impl_tuple!(
695    (A, 0, a),
696    (B, 1, b),
697    (C, 2, c),
698    (D, 3, d),
699    (E, 4, e),
700    (F, 5, f)
701);
702impl_tuple!(
703    (A, 0, a),
704    (B, 1, b),
705    (C, 2, c),
706    (D, 3, d),
707    (E, 4, e),
708    (F, 5, f),
709    (G, 6, g)
710);
711impl_tuple!(
712    (A, 0, a),
713    (B, 1, b),
714    (C, 2, c),
715    (D, 3, d),
716    (E, 4, e),
717    (F, 5, f),
718    (G, 6, g),
719    (H, 7, h)
720);