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
12pub trait Collate<Sample> {
17 type Batch;
19
20 type Error;
22
23 fn collate(&mut self, samples: Vec<Sample>) -> std::result::Result<Self::Batch, Self::Error>;
25}
26
27#[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#[derive(Clone, Copy, Debug)]
81pub struct FnCollate<F> {
82 collate: F,
83}
84
85impl<F> FnCollate<F> {
86 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#[derive(Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
121pub struct Bytes(pub Vec<u8>);
122
123#[derive(Debug)]
128#[non_exhaustive]
129pub enum CollateError {
130 EmptyBatch,
132 ConversionBatchSize {
134 actual: usize,
136 },
137 SequenceLengthMismatch {
139 sample: usize,
141 expected: usize,
143 actual: usize,
145 },
146 OptionPresenceMismatch {
148 sample: usize,
150 expected_some: bool,
152 actual_some: bool,
154 },
155 MapKeysMismatch {
157 sample: usize,
159 },
160 SizeOverflow {
162 context: &'static str,
164 value: usize,
166 },
167 Allocation {
169 context: &'static str,
171 requested: usize,
173 source: TryReserveError,
175 },
176 LibTorch {
178 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
271pub trait DefaultCollate: Sized {
282 type Batch;
284
285 fn default_collate(samples: Vec<Self>) -> std::result::Result<Self::Batch, CollateError>;
287}
288
289#[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
516pub trait DefaultConvert: Sized {
526 type Output;
528
529 fn default_convert(self) -> std::result::Result<Self::Output, CollateError>;
531}
532
533#[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 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);