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

//! Identity layer that passes its input through unchanged, and parks the input shape for
//! backpropagation
//!
//! The layer accepts nonempty tensors with a batch axis and emits values in C order.
//! Training caches the input shape to validate the backward gradient.

use crate::error::Error;
use crate::neural_network::layers::ParamCounts;
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};

/// Passes its input through unchanged
///
/// The output equals each nonempty input with rank 1 or higher. The backward pass returns the
/// gradient it receives. The layer holds no parameter and reads no configuration
///
/// Its use is a placeholder. A function that chooses among several layers to build a model
/// needs something to return when the choice is "no operation". A stack whose depth is a
/// runtime value needs a filler that leaves the activations alone. Both are cleaner with a
/// layer that does nothing than with an `Option` at every position
///
/// # 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::Array2;
///
/// // A rank-2 input: 2 samples of 3 features each.
/// let x = Array2::from_shape_vec((2, 3), vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0])
///     .unwrap()
///     .into_dyn();
///
/// let mut model = SequentialBuilder::new()
///     .add(Identity::new())
///     .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 same = model.predict(&x).unwrap();
///
/// // Every value comes back untouched.
/// assert_eq!(same, x);
/// ```
///
/// # Performance
///
/// The layer always copies its input, because a layer implementation returns an owned tensor
#[derive(Debug, Default)]
pub struct Identity {
    /// Shape the layer was built for, batch axis first. `None` before the build
    built: Option<Shape>,
}

impl Identity {
    /// Creates a new Identity layer
    ///
    /// # Returns
    ///
    /// - `Self` - New `Identity` layer instance
    pub fn new() -> Self {
        Identity::default()
    }

    /// Checks the rank and the element count of a tensor entering the layer
    ///
    /// # Errors
    ///
    /// - `Error::InvalidInput` - If the input has no batch axis
    /// - `Error::EmptyInput` - If any axis has an extent of 0
    fn validate(input: &Tensor) -> Result<(), Error> {
        if input.ndim() == 0 {
            return Err(Error::invalid_input(
                "Identity layer expects an input with a batch axis, got a 0D tensor",
            ));
        }
        if input.is_empty() {
            return Err(Error::empty_input("input tensor"));
        }
        Ok(())
    }
}

/// Copies `input` into a tensor that is in C order
///
/// Every layer here emits C order, so a consumer can read any layer output as 1 contiguous
/// slice. An input that arrives in another layout therefore cannot pass straight through
fn copy_in_c_order(input: &Tensor) -> Tensor {
    input.as_standard_layout().into_owned()
}

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

    built_layer_shape_functions!();

    no_trainable_parameters_layer_functions!();
}

impl UnaryLayer for Identity {
    /// Records the shape the layer passes through. The layer holds no array, so nothing is
    /// allocated
    fn build(&mut self, input: &Shape) -> Result<(), Error> {
        let Some(built) = start_build(&self.built, "Identity", 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> {
        Self::validate(input)?;

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

        Ok(copy_in_c_order(input))
    }

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

        if grad_output.shape() != input_shape.as_slice() {
            return Err(Error::shape_mismatch(input_shape, grad_output.shape()));
        }

        Ok(copy_in_c_order(grad_output))
    }
}