v1 0.0.0

Scalar mathematical library for neural networks.
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

// libs/v1/src/ml/init.rs
//
//! # Математика инициализации весов (Weight Initialization)
//!
//! Модуль содержит чистые скалярные функции для расчета масштабов и границ
//! распределений весов нейросети. Правильная инициализация удерживает дисперсию
//! сигналов и градиентов в стабильном диапазоне, предотвращая затухание
//! или взрыв градиентов при прохождении через глубокие слои.

/// # Равномерная инициализация Ксавье (Xavier / Glorot Uniform)
///
/// Рассчитывает границу диапазона `[-r, r]` для равномерного распределения.
/// Рекомендуется для сетей с гладкими функциями активации (`Sigmoid`, `Tanh`).
///
/// ### График плотности распределения:
/// ```text
///      Плотность (f)
///          |_________
///          |         |
///     ____.|_________|.___> Веса
///         -r    0    r
/// ```
///
/// ### Формула
/// ```text
/// r = sqrt(6 / (inputs + outputs))
/// ```
///
/// ### Примеры
/// ```
/// use v1::ml::init::xavier_uniform_bound;
///
/// let r = xavier_uniform_bound(100, 100);
/// assert!(r > 0.0);
/// // При inputs=100, outputs=100 -> sqrt(6/200) = sqrt(0.03) ≈ 0.173205
/// assert!((r - 0.173205).abs() < 1e-5);
/// ```
pub fn xavier_uniform_bound(inputs: usize, outputs: usize) -> f32 {
    if inputs == 0 && outputs == 0 {
        return 0.0;
    }
    // Безопасное сложение для защиты от usize::MAX
    match inputs.checked_add(outputs) {
        Some(sum) => (6.0 / sum as f32).sqrt(),
        None => 0.0,
    }
}

/// # Нормальная инициализация Ксавье (Xavier / Glorot Normal)
///
/// Масштабирует сырое случайное число из стандартного нормального распределения
/// под целевое распределение Ксавье.
///
/// ### Формула
/// ```text
/// std_dev = sqrt(2 / (inputs + outputs))
/// result = random_sample * std_dev
/// ```
///
/// ### Примеры
/// ```
/// use v1::ml::init::xavier_normal_scale;
///
/// // Сырой сэмпл равен 1.0, inputs=100, outputs=100 -> sqrt(2/200) = sqrt(0.01) = 0.1
/// let weight = xavier_normal_scale(1.0, 100, 100);
/// assert!((weight - 0.1).abs() < 1e-6);
/// ```
pub fn xavier_normal_scale(random_sample: f32, inputs: usize, outputs: usize) -> f32 {
    if inputs == 0 && outputs == 0 {
        return 0.0;
    }
    // Используем канонический std_dev = sqrt(2 / (inputs + outputs))
    match inputs.checked_add(outputs) {
        Some(sum) => {
            let std_dev = (2.0 / sum as f32).sqrt();
            random_sample * std_dev
        },
        None => 0.0,
    }
}

/// # Равномерная инициализация Хэ (He / Kaiming Uniform)
///
/// Рассчитывает границу диапазона `[-r, r]` для равномерного распределения.
/// Разработана специально для глубоких сетей, использующих функции активации с
/// "мертвой" отрицательной зоной (`ReLU`, `LeakyReLU`, `GELU`, `SiLU`). Дисперсия
/// увеличена в два раза по сравнению с Ксавье для компенсации затухания сигналов.
///
/// ### Формула
/// ```text
/// r = sqrt(6 / inputs)
/// ```
///
/// ### Примеры
/// ```
/// use v1::ml::init::he_uniform_bound;
///
/// let r = he_uniform_bound(100);
/// // При inputs=100 -> sqrt(6/100) = sqrt(0.06) ≈ 0.244949
/// assert!((r - 0.244949).abs() < 1e-5);
/// ```
pub fn he_uniform_bound(inputs: usize) -> f32 {
    if inputs == 0 {
        return 0.0;
    }
    (6.0 / inputs as f32).sqrt()
}

/// # Нормальная инициализация Хэ (He / Kaiming Normal)
///
/// Масштабирует сырое случайное число из стандартного нормального распределения
/// под целевое распределение Хэ.
///
/// ### Формула
/// ```text
/// std_dev = sqrt(2 / inputs)
/// result = random_sample * std_dev
/// ```
///
/// ### Примеры
/// ```
/// use v1::ml::init::he_normal_scale;
///
/// // Сырой сэмпл равен 1.0, inputs=50 -> sqrt(2/50) = sqrt(0.04) = 0.2
/// let weight = he_normal_scale(1.0, 50);
/// assert!((weight - 0.2).abs() < 1e-6);
/// ```
pub fn he_normal_scale(random_sample: f32, inputs: usize) -> f32 {
    if inputs == 0 {
        return 0.0;
    }
    let std_dev = (2.0 / inputs as f32).sqrt();
    random_sample * std_dev
}