rustorch 0.6.29

# Обзор Python привязок RusTorch

## Обзор

RusTorch — это высокопроизводительный фреймворк для глубокого обучения, реализованный на Rust, предоставляющий API, похожие на PyTorch, при этом используя преимущества безопасности и производительности Rust. Через Python привязки вы можете получить доступ к функциональности RusTorch прямо из Python.

## Ключевые особенности

### 🚀 **Высокая производительность**
- **Ядро Rust**: Достигает производительности уровня C++, обеспечивая безопасность памяти
- **Поддержка SIMD**: Автоматическая векторизация для оптимизированных численных вычислений
- **Параллельная обработка**: Эффективные параллельные вычисления с использованием rayon
- **Нулевое копирование**: Минимальное копирование данных между NumPy и RusTorch

### 🛡️ **Безопасность**
- **Безопасность памяти**: Предотвращает утечки памяти и гонки данных через систему владения Rust
- **Безопасность типов**: Проверка типов во время компиляции снижает ошибки выполнения
- **Обработка ошибок**: Комплексная обработка ошибок с автоматическим преобразованием в исключения Python

### 🎯 **Простота использования**
- **PyTorch-совместимый API**: Простая миграция с существующего кода PyTorch
- **API высокого уровня в стиле Keras**: Интуитивные интерфейсы как model.fit()
- **Интеграция NumPy**: Двустороннее преобразование с массивами NumPy

## Архитектура

Python привязки RusTorch состоят из 10 модулей:

### 1. **tensor** - Операции с тензорами
```python
import rustorch

# Создание тензоров
x = rustorch.tensor([[1.0, 2.0], [3.0, 4.0]])
y = rustorch.zeros((3, 3))
z = rustorch.randn((2, 2))

# Интеграция NumPy
import numpy as np
np_array = np.array([[1, 2], [3, 4]], dtype=np.float32)
torch_tensor = rustorch.from_numpy(np_array)
```

### 2. **autograd** - Автоматическое дифференцирование
```python
# Вычисление градиентов
x = rustorch.tensor([[1.0, 2.0]], requires_grad=True)
y = x.pow(2).sum()
y.backward()
print(x.grad)  # Получить градиенты
```

### 3. **nn** - Нейронные сети
```python
# Создание слоев
linear = rustorch.nn.Linear(10, 1)
conv2d = rustorch.nn.Conv2d(3, 64, kernel_size=3)
relu = rustorch.nn.ReLU()

# Функции потерь
mse_loss = rustorch.nn.MSELoss()
cross_entropy = rustorch.nn.CrossEntropyLoss()
```

### 4. **optim** - Оптимизаторы
```python
# Оптимизаторы
optimizer = rustorch.optim.Adam(model.parameters(), lr=0.001)
sgd = rustorch.optim.SGD(model.parameters(), lr=0.01, momentum=0.9)

# Планировщики скорости обучения
scheduler = rustorch.optim.lr_scheduler.StepLR(optimizer, step_size=10)
```

### 5. **data** - Загрузка данных
```python
# Создание набора данных
dataset = rustorch.data.TensorDataset(data, targets)
dataloader = rustorch.data.DataLoader(dataset, batch_size=32, shuffle=True)

# Преобразования данных
transform = rustorch.data.transforms.Normalize(mean=0.5, std=0.2)
```

### 6. **training** - API обучения высокого уровня
```python
# API в стиле Keras
model = rustorch.Model()
model.add("Dense(64, activation=relu)")
model.add("Dense(10, activation=softmax)")
model.compile(optimizer="adam", loss="categorical_crossentropy")

# Выполнение обучения
history = model.fit(train_data, validation_data=val_data, epochs=10)
```

### 7. **distributed** - Распределенное обучение
```python
# Настройка распределенного обучения
config = rustorch.distributed.DistributedConfig(
    backend="nccl", world_size=4, rank=0
)

# Параллелизм данных
model = rustorch.distributed.DistributedDataParallel(model)
```

### 8. **visualization** - Визуализация
```python
# Построить историю обучения
plotter = rustorch.visualization.Plotter()
plotter.plot_training_history(history, save_path="training.png")

# Визуализация тензора
plotter.plot_tensor_as_image(tensor, title="Карта признаков")
```

### 9. **utils** - Утилиты
```python
# Сохранить/загрузить модель
rustorch.utils.save_model(model, "model.rustorch")
loaded_model = rustorch.utils.load_model("model.rustorch")

# Профилирование
profiler = rustorch.utils.Profiler()
with profiler.profile():
    output = model(input_data)
```

## Установка

### Предварительные требования
- Python 3.8+
- Rust 1.70+
- CUDA 11.8+ (для использования GPU)

### Сборка и установка
```bash
# Клонировать репозиторий
git clone https://github.com/JunSuzukiJapan/RusTorch
cd RusTorch/rustorch

# Создать виртуальную среду Python
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# Установить зависимости
pip install maturin numpy

# Собрать и установить
maturin develop --release

# Или установить из PyPI (планируется в будущем)
# pip install rustorch
```

## Быстрый старт

### 1. Базовые операции с тензорами
```python
import rustorch
import numpy as np

# Создание тензора
x = rustorch.tensor([[1.0, 2.0], [3.0, 4.0]])
print(f"Форма: {x.shape()}")  # Форма: [2, 2]

# Математические операции
y = x + 2.0
z = x.matmul(y.transpose(0, 1))
print(f"Результат: {z.to_numpy()}")
```

### 2. Пример линейной регрессии
```python
import rustorch
import numpy as np

# Генерация данных
np.random.seed(42)
X = np.random.randn(100, 1).astype(np.float32)
y = 2 * X + 1 + 0.1 * np.random.randn(100, 1).astype(np.float32)

# Преобразование в тензоры
X_tensor = rustorch.from_numpy(X)
y_tensor = rustorch.from_numpy(y)

# Определение модели
model = rustorch.Model()
model.add("Dense(1)")
model.compile(optimizer="sgd", loss="mse")

# Создание набора данных
dataset = rustorch.data.TensorDataset(X_tensor, y_tensor)
dataloader = rustorch.data.DataLoader(dataset, batch_size=10)

# Обучение
history = model.fit(dataloader, epochs=100, verbose=True)

# Отображение результатов
print(f"Финальная потеря: {history.train_loss()[-1]:.4f}")
```

### 3. Классификация с нейронной сетью
```python
import rustorch

# Подготовка данных
train_dataset = rustorch.data.TensorDataset(train_X, train_y)
train_loader = rustorch.data.DataLoader(
    train_dataset, batch_size=64, shuffle=True
)

# Построение модели
model = rustorch.Model("КлассификационнаяСеть")
model.add("Dense(128, activation=relu)")
model.add("Dropout(0.3)")
model.add("Dense(64, activation=relu)")  
model.add("Dense(10, activation=softmax)")

# Компиляция модели
model.compile(
    optimizer="adam",
    loss="categorical_crossentropy",
    metrics=["accuracy"]
)

# Настройка обучения
config = rustorch.training.TrainerConfig(
    epochs=50,
    learning_rate=0.001,
    validation_frequency=5
)
trainer = rustorch.training.Trainer(config)

# Обучение
history = trainer.train(model, train_loader, val_loader)

# Оценка
metrics = model.evaluate(test_loader)
print(f"Точность теста: {metrics['accuracy']:.4f}")
```

## Оптимизация производительности

### Использование SIMD
```python
# Включить SIMD-оптимизацию во время сборки
# Cargo.toml: target-features = "+avx2,+fma"

x = rustorch.randn((1000, 1000))
y = x.sqrt()  # SIMD-оптимизированное вычисление
```

### Использование GPU
```python
# Использование CUDA (планируется в будущем)
device = rustorch.cuda.device(0)
x = rustorch.randn((1000, 1000)).to(device)
y = x.matmul(x.transpose(0, 1))  # GPU вычисление
```

### Параллельная загрузка данных
```python
dataloader = rustorch.data.DataLoader(
    dataset,
    batch_size=64,
    shuffle=True,
    num_workers=4  # Количество параллельных воркеров
)
```

## Лучшие практики

### 1. Эффективность памяти
```python
# Использовать преобразование с нулевым копированием
np_array = np.array([[1, 2], [3, 4]], dtype=np.float32)
tensor = rustorch.from_numpy(np_array)  # Без копирования

# Использовать операции на месте
tensor.add_(1.0)  # Эффективное использование памяти
```

### 2. Обработка ошибок
```python
try:
    result = model(неверный_ввод)
except rustorch.RusTorchError as e:
    print(f"Ошибка RusTorch: {e}")
except Exception as e:
    print(f"Неожиданная ошибка: {e}")
```

### 3. Отладка и профилирование
```python
# Использовать профилировщик
profiler = rustorch.utils.Profiler()
profiler.start()

# Выполнить вычисления
output = model(input_data)

profiler.stop()
print(profiler.summary())
```

## Ограничения

### Текущие ограничения
- **Поддержка GPU**: Поддержка CUDA/ROCm в разработке
- **Динамические графы**: В настоящее время поддерживает только статические графы
- **Распределенное обучение**: Реализована только базовая функциональность

### Будущие расширения
- GPU ускорение (CUDA, Metal, ROCm)
- Поддержка динамических вычислительных графов
- Больше слоев нейронных сетей
- Квантование и обрезка моделей
- Функциональность экспорта ONNX

## Вклад

### Участие в разработке
```bash
# Настройка среды разработки
git clone https://github.com/JunSuzukiJapan/RusTorch
cd RusTorch/rustorch
pip install -e .[dev]

# Запуск тестов
cargo test
python -m pytest tests/

# Проверка качества кода
cargo clippy
cargo fmt
```

### Сообщество
- GitHub Issues: Отчеты об ошибках и запросы функций
- Discussions: Вопросы и обсуждения
- Discord: Поддержка в реальном времени

## Лицензия

RusTorch выпускается под лицензией MIT. Свободно для использования как в коммерческих, так и некоммерческих целях.

## Связанные ссылки

- [GitHub репозиторий](https://github.com/JunSuzukiJapan/RusTorch)
- [API документация](./python_api_reference.md)
- [Примеры и туториалы](../examples/)
- [Бенчмарки производительности](./benchmarks.md)