rustyml 0.17.0

Machine learning models, neural networks, metrics, and data utilities in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

//! 1D upsampling layer that repeats each step along the length axis
//!
//! [`UpSampling1D`] enlarges the step axis of a `[batch, steps, features]` tensor. It holds no
//! parameter and takes no interpolation mode, because copying a step needs no weight. The forward
//! and backward passes both run through `resize_engine`, which treats the repeat as a
//! fixed-weight gather in each direction.

use crate::error::Error;
use crate::neural_network::layers::ParamCounts;
use crate::neural_network::layers::upsampling::Interpolation;
use crate::neural_network::layers::upsampling::resize_engine::{
    upsample_backward, upsample_forward, upsample_output_shape, validate_factors,
};
use crate::neural_network::layers::validation::start_build;
use crate::neural_network::layers::{
    built_layer_shape_functions, no_trainable_parameters_layer_functions,
};
use crate::neural_network::traits::{LayerBase, UnaryLayer};
use crate::neural_network::{Ctx, Shape, Tensor};

/// Repeats each step of the step axis of a rank-3 tensor
///
/// The input shape is `[batch_size, steps, features]`. The output shape is
/// `[batch_size, steps * size, features]`. The batch axis and the feature axis pass through
/// unchanged
///
/// The layer holds no parameter. Each output step copies the input step it came from, so the
/// layer takes no interpolation argument
///
/// The layer is the decoder counterpart of
/// [`MaxPooling1D`](crate::neural_network::layers::pooling::MaxPooling1D) and
/// [`AveragePooling1D`](crate::neural_network::layers::pooling::AveragePooling1D). A pooling
/// stage of `pool_size` and an upsampling stage of the same `size` restore the original length
///
/// # Examples
///
/// ```rust
/// use rustyml::neural_network::Shape;
/// use rustyml::neural_network::sequential::SequentialBuilder;
/// use rustyml::neural_network::layers::*;
/// use rustyml::neural_network::optimizers::*;
/// use rustyml::neural_network::losses::*;
/// use ndarray::Array3;
///
/// // A rank-3 input: 1 sample, 2 steps, 2 features.
/// let x = Array3::from_shape_vec((1, 2, 2), vec![1.0, 2.0, 3.0, 4.0])
///     .unwrap()
///     .into_dyn();
///
/// let mut model = SequentialBuilder::new()
///     .add(UpSampling1D::new(3).unwrap())
///     .build(&Shape::known(x.shape()))
///     .unwrap();
/// model.compile(SGD::new(0.01, 0.0, false, 0.0).unwrap(), MeanSquaredError::new());
///
/// // View model structure.
/// model.summary();
///
/// let longer = model.predict(&x).unwrap();
///
/// // 2 steps become 6, and each input step covers 3 of them.
/// assert_eq!(longer.shape(), &[1, 6, 2]);
/// assert_eq!(longer[[0, 0, 0]], 1.0);
/// assert_eq!(longer[[0, 2, 0]], 1.0);
/// assert_eq!(longer[[0, 3, 0]], 3.0);
/// ```
#[derive(Debug)]
pub struct UpSampling1D {
    /// Times the layer repeats each step
    size: usize,
    /// Shape the layer was built for, batch axis first. `None` before the build
    built: Option<Shape>,
}

impl UpSampling1D {
    /// Creates a new UpSampling1D layer
    ///
    /// # Parameters
    ///
    /// - `size` - Times the layer repeats each step. A size of 1 leaves the length alone
    ///
    /// # Returns
    ///
    /// - `Result<Self, Error>` - New `UpSampling1D` layer instance
    ///
    /// # Errors
    ///
    /// - `Error::InvalidParameter` - If `size` is 0
    pub fn new(size: usize) -> Result<Self, Error> {
        validate_factors(&[size])?;
        Ok(UpSampling1D { size, built: None })
    }
}

impl LayerBase for UpSampling1D {
    fn layer_type(&self) -> &str {
        "UpSampling1D"
    }

    built_layer_shape_functions!();

    no_trainable_parameters_layer_functions!();
}

impl UnaryLayer for UpSampling1D {
    /// Records the shape the layer enlarges. The layer holds no array, so nothing is allocated.
    /// The shape algebra checks the rank
    fn build(&mut self, input: &Shape) -> Result<(), Error> {
        let Some(built) = start_build(&self.built, "UpSampling1D", input)? else {
            return Ok(());
        };
        self.compute_output_shape(&built)?;
        self.built = Some(built);
        Ok(())
    }

    fn forward(&self, input: &Tensor, ctx: &mut Ctx) -> Result<Tensor, Error> {
        let output = upsample_forward(
            input,
            &[self.size],
            Interpolation::Nearest,
            3,
            "UpSampling1D",
        )?;

        if ctx.is_training() {
            ctx.push_cache("UpSampling1D", input.shape().to_vec());
        }

        Ok(output)
    }

    fn backward(&self, grad_output: &Tensor, ctx: &mut Ctx) -> Result<Tensor, Error> {
        let input_shape: Vec<usize> = ctx.pop_cache("UpSampling1D")?;

        upsample_backward(
            grad_output,
            Some(input_shape.as_slice()),
            &[self.size],
            Interpolation::Nearest,
            "UpSampling1D",
        )
    }

    fn compute_output_shape(&self, input: &Shape) -> Result<Shape, Error> {
        upsample_output_shape(input, &[self.size], "UpSampling1D")
    }
}