<div align="center">
# V1
[](https://www.apache.org/licenses/LICENSE-2.0.txt)
[](https://www.rust-lang.org)
</div>
V1 — это библиотека для математических вычислений и машинного обучения. V1 предоставляет математические функции в виде обычных функций, которые можно использовать, не писая сложные выражения.
**Включает**:
- функции активации (GELU, ReLU, SiLU...)
- функции потерь (MSE, MAE, Huber)
- инструменты финансовой математики (SMA, EMA, CAGR)
## Установка
Добавьте в ваш `Cargo.toml`:
```bash
cargo add v1
```
## Быстрый старт
### Функции активации
```rust
use v1::ml::activation::*;
// GELU активация с аппроксимацией tanh
let x = 2.0;
let result = gelu_tanh(x);
// ReLU: обнуляет отрицательные значения
let relu_out = relu(x);
// SiLU: сигмоидно-взвешенный линейный блок
let silu_out = silu(x);
```
### Функции потерь
```rust
use v1::ml::loss::*;
let prediction = 0.8;
let target = 1.0;
// Среднеквадратичная ошибка
let mse = mse(prediction, target);
let mse_grad = mse_grad(prediction, target);
// Средняя абсолютная ошибка
let mae = mae(prediction, target);
// Потеря Хубера (устойчива к выбросам)
let huber = huber(prediction, target, 1.0);
```
### Инициализация весов
```rust
use v1::ml::weight_init::*;
let n_in = 64;
let n_out = 128;
// Инициализация Xavier для sigmoid/tanh
let xavier_scale = xavier_normal(n_in, n_out);
// Инициализация He для ReLU/GELU
let he_scale = he_normal(n_in);
```
### Финансовый анализ
```rust
use v1::finance::*;
// Простая скользящая средняя
let mut sma = 0.0;
sma = sma_update(sma, 100.0, 20); // SMA периода 20
// Экспоненциальная скользящая средняя
let mut ema = 0.0;
ema = ema_update(ema, 100.0, 20); // EMA периода 20
// CAGR: совокупный среднегодовой темп роста
let initial = 1000.0;
let final_value = 2000.0;
let years = 5.0;
let cagr = cagr(initial, final_value, years);
```
## Документация
<details>
<summary>Машинное обучение</summary>
## Какие математические функции включены в `V1`
## Функции активации в `V1`
## GELU (`G`aussian `E`rror `L`inear `U`nit)
Гладкая функция для активации нейронов. В библиотеке V1 есть несколько способов её вычисления:
- Аппроксимация через гиперболический тангенс
Наиболее точный и стандартный вариант аппроксимации.
**Формула**
$$GELU(x) \approx 0.5x \left( 1 + \tanh\left( \sqrt{\frac{2}{\pi}} \left( x + 0.044715x^3 \right) \right) \right)$$
---
- Аппроксимация сигмоидом
Более быстрая альтернатива, вычисляется через масштабированную логистическую функцию.
**Формула**
$$GELU(x) \approx x \cdot \sigma(1.702 \cdot x) = \frac{x}{1 + e^{-1.702x}}$$
Где $\sigma(x)$ — стандартная логистическая функция (сигмоид).
---
## ReLU (`Re`ctified `L`inear `U`nit)
Популярная и быстрая нелинейная функция для активации нейронов. Принимает `x`, и если число отрицательное, преобразует его в 0. Положительные числа остаются без изменений.
**Формула**
$$ReLU(x) = \max(0, x)$$
---
## Softplus
Гладкая и непрерывная альтернатива функции ReLU, которая не имеет резкого излома в нуле. Позволяет сохранить микро-градиенты в отрицательной области значений.
**Формула**
$$Softplus(x) = \ln(1 + e^x)$$
---
## SiLU (`Si`gmoid `L`inear `U`nit / Swish)
Функция активации, которая взвешивает входное значение по его сигмоидальной вероятности. Является де-факто стандартом в архитектурах современных языковых моделей (LLaMA, Mistral).
**Формула**
$$SiLU(x) = x \cdot \sigma(x) = \frac{x}{1 + e^{-x}}$$
Где $\sigma(x)$ — стандартная логистическая функция (сигмоид).
---
## ELU (`E`xponential `L`inear `U`nit)
Экспоненциальный линейный блок, который сглаживает отрицательную полуплоскость. Это позволяет среднему значению активаций на слое быть ближе к нулю, что значительно ускоряет сходимость и обучение нейронной сети.
**Формула**
$$ELU(x) = \begin{cases} x, & \text{если } x > 0 \\ \alpha(e^x - 1), & \text{если} x \le 0 \end{cases}$$
Где $\alpha$ (альфа) — коэффициент масштабирования отрицательной области (обычно 1.0).
---
## Модуль функций потерь
Скалярные потери и их производные (градиенты), предназначенные для вычисления ошибки на отдельных узлах вычислительного графика.
## MSE (`M`ean `S`quared `E`rror)
Квадратичная потеря. Резко увеличивает штраф за серьёзные отклонения.
* **Функция**
$L = (pred - target)^2$
* **Градиент**
$\frac{\partial L}{\partial pred} = 2 \cdot (pred - target)$
## MAE (`M`ean `A`bsolute `E`rror)
Линейная потеря. Устойчива к аномалиям (выбросам) в обучающей выборке.
* **Функция:** $L = |pred - target|$
* **Градиент:** $\frac{\partial L}{\partial pred} = sign(pred - target)$
## Потеря Хубера
Гибридная устойчивая потеря. Объединяет лучшие свойства MSE (гладкость вблизи нуля) и MAE (линейный предел на больших ошибках, защита от взрыва градиентов).
* **Функция:** $$L = \begin{cases} 0.5 \cdot (pred - target)^2, & \text{если } |pred - target| \le \delta \\ \delta \cdot (|pred - target| - 0.5 \cdot \delta), & \text{если } |pred - target| > \delta \end{cases}$$
---
## Модуль инициализации весов
Скалярные функции для вычисления начального масштаба весов модели. Они защищают сеть от затухания или взрыва градиентов на первых шагах обучения без использования встроенных генераторов случайных чисел.
## Инициализация Xavier (Glorot)
Рекомендуется для сетей с гладкими функциями активации (Sigmoid, Tanh).
* **Граница равномерного распределения:**$$r= \sqrt{\frac{6}{n_{in} + n_{out}}}$$
* **Масштаб нормального распределения:** $$\sigma = \sqrt{\frac{2}{n_{in} + n_{out}}}$$
## Инициализация He (Kaiming)
Рекомендуется для сетей с нелинейными функциями активации (ReLU, LeakyReLU, GELU, SiLU).
* **Граница равномерного распределения:** $$r= \sqrt{\frac{6}{n_{in}}}$$
* **Масштаб нормального распределения:** $$\sigma = \sqrt{\frac{2}{n_{in}}}$$
</details>
<details>
<summary>Финансовая математика</summary>
## Модуль финансовой математики
Скалярные функции для технического анализа рынков, фильтрации временных рядов и оценки инвестиций. Разработаны без выделения памяти в куче для максимальной скорости в HFT-системах.
## Фильтры тренда (Скользящие средние)
### SMA (`S`imple `M`oving `A`verage)
Простая скользящая средняя. Сглаживает колебания цен, вычисляя среднее арифметическое в скользящем окне.
* **Формула обновления**
$$SMA_{new} = SMA_{old} + \frac{price_{new} - price_{old}}{N}$$
### EMA (`E`xponential `M`oving `A`verage)
Экспоненциальная скользящая средняя. Дает больший вес последним ценам. Математический аналог механизма Momentum в оптимизаторах нейронных сетей.
* **Формула**
$$EMA_t = \alpha \cdot price_t + (1 - \alpha) \cdot EMA_{t-1}$$
Где $\alpha = \frac{2}{N + 1}$ — коэффициент сглаживания.
---
## Математика рыночных осцилляторов
Вместо тяжелых индикаторов с сохранением истории, модуль предоставляет чистые атомарные компоненты для нормализации финансовых диапазонов.
### RS (`R`elative `S`trength)
Коэффициент относительной силы. Находит чистую математическую пропорцию между средним ростом и средним падением актива.
* **Формула**
$$RS = \frac{\text{Средний прирост}}{\text{Средний убыток}}$$
## Сжатие RSI (сжатие финансового диапазона)
Это скалярная функция нормализации, которая принимает коэффициент импульса $RS$ и нелинейно упаковывает его в жесткие границы от 0.0 до 100.0. Это математический аналог сигмоида для временных рядов.
* **Формула**
$$RSI(RS) = 100 - \frac{100}{1 + RS}$$
---
## Метрики инвестиций (Метрики стоимости)
### CAGR (`C`ompound `A`nnual `G`rowth `R`ate)
Совокупный среднегодовой темп роста. Показывает реальный средний доход от инвестиционного актива за период, полностью сглаживая промежуточную волатильность.
* **Формула**
$$CAGR = \left( \frac{V_{final}}{V_{initial}} \right)^{\frac{1}{n}} - 1.0$$
Где $n$ — количество лет (или периодов).
</details>