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

//! Shared parameter and shape validation helpers for regularization layers
//!
//! Every function checks 1 constructor argument or input shape and returns
//! [`Error::InvalidParameter`] or
//! [`Error::InvalidInput`] on failure. None of them panics.
//!
//! The dropout and noise-injection layers use `validate_rate`, `validate_rate_exclusive`,
//! `validate_stddev`, and `validate_input_ndim`. The normalization layers use
//! `validate_epsilon`, `validate_momentum`, `validate_num_groups`,
//! `validate_num_groups_positive`, and `validate_min_input_ndim`.
//!
//! [`Error::InvalidParameter`]: crate::error::Error::InvalidParameter
//! [`Error::InvalidInput`]: crate::error::Error::InvalidInput

use crate::error::Error;

/// Validates that a rate parameter is between 0.0 and 1.0 (inclusive)
pub(super) fn validate_rate(rate: f32, param_name: &str) -> Result<(), Error> {
    if !(0.0..=1.0).contains(&rate) {
        return Err(Error::invalid_parameter(
            param_name.to_string(),
            format!("must be between 0 and 1, got {}", rate),
        ));
    }
    Ok(())
}

/// Validates that a rate parameter is between 0.0 and 1.0 (exclusive of 1.0)
pub(super) fn validate_rate_exclusive(rate: f32, param_name: &str) -> Result<(), Error> {
    if !(0.0..1.0).contains(&rate) {
        return Err(Error::invalid_parameter(
            param_name.to_string(),
            format!("must be in range [0, 1), got {}", rate),
        ));
    }
    Ok(())
}

/// Validates that input has the expected number of dimensions
pub(super) fn validate_input_ndim(
    input_ndim: usize,
    expected_ndim: usize,
    layer_name: &str,
) -> Result<(), Error> {
    if input_ndim != expected_ndim {
        return Err(Error::invalid_input(format!(
            "{} expects {}D input, got {}D",
            layer_name, expected_ndim, input_ndim
        )));
    }
    Ok(())
}

/// Validates that input has at least the minimum number of dimensions
pub(super) fn validate_min_input_ndim(
    input_ndim: usize,
    min_ndim: usize,
    layer_name: &str,
) -> Result<(), Error> {
    if input_ndim < min_ndim {
        return Err(Error::invalid_input(format!(
            "{} expects at least {}D input, got {}D",
            layer_name, min_ndim, input_ndim
        )));
    }
    Ok(())
}

/// Validates that a standard deviation parameter is non-negative and finite
pub(super) fn validate_stddev(stddev: f32) -> Result<(), Error> {
    if stddev < 0.0 {
        return Err(Error::invalid_parameter(
            "stddev",
            "Standard deviation cannot be negative",
        ));
    }
    // A non-finite stddev (NaN or infinity) would reach `Normal::new(..).unwrap()` in the forward
    // pass. That call panics, so this function rejects it up front.
    if !stddev.is_finite() {
        return Err(Error::invalid_parameter(
            "stddev",
            format!("Standard deviation must be finite, got {}", stddev),
        ));
    }
    Ok(())
}

/// Validates that epsilon is positive and finite
pub(super) fn validate_epsilon(epsilon: f32) -> Result<(), Error> {
    if epsilon <= 0.0 {
        return Err(Error::invalid_parameter(
            "epsilon",
            format!("Epsilon must be positive, got {}", epsilon),
        ));
    }
    if !epsilon.is_finite() {
        return Err(Error::invalid_parameter(
            "epsilon",
            format!("Epsilon must be finite, got {}", epsilon),
        ));
    }
    Ok(())
}

/// Validates that momentum is between 0.0 and 1.0 (inclusive)
pub(super) fn validate_momentum(momentum: f32) -> Result<(), Error> {
    if !(0.0..=1.0).contains(&momentum) {
        return Err(Error::invalid_parameter(
            "momentum",
            format!("Momentum must be between 0.0 and 1.0, got {}", momentum),
        ));
    }
    Ok(())
}

/// Validates that num_groups divides num_channels evenly
pub(super) fn validate_num_groups(num_channels: usize, num_groups: usize) -> Result<(), Error> {
    if !num_channels.is_multiple_of(num_groups) {
        return Err(Error::invalid_parameter(
            "num_groups",
            format!(
                "Number of channels ({}) must be divisible by num_groups ({})",
                num_channels, num_groups
            ),
        ));
    }
    Ok(())
}

/// Validates that num_groups is greater than 0
pub(super) fn validate_num_groups_positive(num_groups: usize) -> Result<(), Error> {
    if num_groups == 0 {
        return Err(Error::invalid_parameter(
            "num_groups",
            "Number of groups must be greater than 0",
        ));
    }
    Ok(())
}