diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..2a1dfba --- /dev/null +++ b/Dockerfile @@ -0,0 +1,12 @@ +FROM python:3.10 + +WORKDIR /app + +COPY requirements.txt . +RUN pip install -r requirements.txt + +COPY . . + +RUN pip install sphinx sphinx-autobuild sphinxcontrib-napoleon sphinx_autodoc_typehints + +CMD ["sphinx-autobuild", "/app/docs/source", "/app/docs/build/html", "--host", "0.0.0.0"] \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..cf54fe2 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,10 @@ +version: '3' +services: + sphinx-docs: + build: . + ports: + - "8000:8000" + volumes: + - ./docs/source:/app/docs/source + - ./docs/build:/app/docs/build + command: sphinx-autobuild /app/docs/source /app/docs/build/html --host 0.0.0.0 \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..dc1312a --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..03d2352 --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,9 @@ +/* Скрыть кнопку "Следующая" */ +a.btn.btn-neutral.float-right[rel="next"] { + display: none; +} + +/* Скрыть кнопку "Предыдущая", если необходимо */ +a.btn.btn-neutral.float-left[rel="prev"] { + display: none; +} \ No newline at end of file diff --git a/docs/source/callbacks.rst b/docs/source/callbacks.rst new file mode 100644 index 0000000..3ba0748 --- /dev/null +++ b/docs/source/callbacks.rst @@ -0,0 +1,879 @@ +Callbacks +========= + +В этой секции представлены различные классы колбеков, используемые в библиотеке **Diffusion**. Колбеки позволяют расширять функциональность тренировочного процесса, добавляя дополнительные шаги или изменяя поведение модели во время обучения. + +.. toctree:: + :maxdepth: 2 + :caption: Содержание + + Callback + TrainCB + DeviceCB + AccelerateCB + HooksCallback + ActivationStats + BaseSchedCB + BatchSchedCB + BatchTransformCB + CapturePredsCB + CompletionCB + DDPMCB + DDPMCB2 + EpochSchedCB + HasLearnCB + ImageLogCB + ImageOptCB + LRFinderCB + MetricsCB + MixedPrecisionCB + MultiGPUsCallback + ProgressCB + RecorderCB + SingleBatchCB + with_cbs +Callback +-------- + +Класс :class:`~callbacks.Callback` является базовым классом для всех колбеков в библиотеке **Diffusion**. Он определяет общую структуру и порядок выполнения колбеков во время тренировочного цикла. + +**Основные атрибуты:** + +- **order**: Определяет порядок выполнения колбека относительно других колбеков. По умолчанию значение `0`. + +**Основные методы:** + +- **`before_fit(self, learn)`**: Вызывается перед началом обучения. +- **`after_fit(self, learn)`**: Вызывается после завершения обучения. +- **`before_batch(self, learn)`**: Вызывается перед обработкой каждого батча. +- **`after_batch(self, learn)`**: Вызывается после обработки каждого батча. +- **`predict(self, learn)`**: Выполняет предсказание модели. +- **`get_loss(self, learn)`**: Вычисляет функцию потерь. +- **`backward(self, learn)`**: Выполняет обратное распространение ошибки. +- **`step(self, learn)`**: Обновляет параметры оптимизатора. +- **`zero_grad(self, learn)`**: Обнуляет градиенты оптимизатора перед новым шагом обучения. + +**Пример использования:** + +.. code-block:: python + + from callbacks import Callback + + class MyCustomCB(Callback): + def before_fit(self, learn): + print("Начало обучения") + + def after_fit(self, learn): + print("Обучение завершено") + +--- + +TrainCB +------- + +Класс :class:`~callbacks.TrainCB` наследуется от базового класса :class:`~callbacks.Callback` и предназначен для управления основными этапами тренировочного цикла, такими как предсказание, вычисление потерь, обратное распространение и обновление оптимизатора. + +**Основные атрибуты:** + +- **n_inp**: Количество входных данных, используемых моделью для предсказания. По умолчанию значение `1`. + +**Основные методы:** + +- **`__init__(self, n_inp=1)`**: Инициализирует колбек с заданным количеством входных данных. +- **`predict(self, learn)`**: Выполняет предсказание модели на основе текущего батча данных. +- **`get_loss(self, learn)`**: Вычисляет функцию потерь между предсказаниями модели и истинными значениями. +- **`backward(self, learn)`**: Выполняет обратное распространение ошибки для вычисленной функции потерь. +- **`step(self, learn)`**: Обновляет параметры оптимизатора на основе вычисленных градиентов. +- **`zero_grad(self, learn)`**: Обнуляет градиенты оптимизатора перед новым шагом обучения. + +**Пример использования:** + +.. code-block:: python + + from callbacks import TrainCB + + class CustomTrainCB(TrainCB): + def get_loss(self, learn): + # Пользовательская функция потерь + learn.loss = custom_loss_function(learn.preds, *learn.batch[self.n_inp:]) + +--- + +DeviceCB +-------- + +Класс :class:`~callbacks.DeviceCB` наследуется от базового класса :class:`~callbacks.Callback` и отвечает за перенос модели и данных на указанное устройство (CPU или GPU). Это обеспечивает эффективное использование вычислительных ресурсов и ускоряет процесс обучения. + +**Основные атрибуты:** + +- **device**: Устройство, на которое будет перенесена модель и данные. Возможные значения: `'cpu'`, `'cuda'` и другие поддерживаемые устройствами. + +**Основные методы:** + +- **`__init__(self, device='cpu')`**: Инициализирует колбек с указанным устройством. +- **`before_fit(self, learn)`**: Переносит модель на указанное устройство перед началом обучения. +- **`before_batch(self, learn)`**: Переносит текущий батч данных на указанное устройство перед обработкой. + +**Пример использования:** + +.. code-block:: python + + from callbacks import DeviceCB + + device_cb = DeviceCB(device='cuda') + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[device_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + +--- + +AccelerateCB +------------ + +Класс :class:`~callbacks.AccelerateCB` наследуется от :class:`~callbacks.TrainCB` и интегрируется с библиотекой [Accelerate](https://github.com/huggingface/accelerate) для упрощения процесса обучения на различных устройствах с поддержкой смешанной точности. + +**Основные атрибуты:** + +- **order**: Определяет порядок выполнения колбека относительно других колбеков. Устанавливается как `DeviceCB.order + 10` для гарантии выполнения после `DeviceCB`. + +**Основные методы:** + +- **`__init__(self, n_inp=1, mixed_precision="fp16")`**: Инициализирует колбек с заданным количеством входных данных и типом смешанной точности. +- **`before_fit(self, learn)`**: Подготавливает модель, оптимизатор и загрузчики данных с помощью `Accelerator` перед началом обучения. +- **`backward(self, learn)`**: Выполняет обратное распространение ошибки с использованием `Accelerator`. + +**Пример использования:** + +.. code-block:: python + + from callbacks import AccelerateCB + + accelerate_cb = AccelerateCB(n_inp=1, mixed_precision="fp16") + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[accelerate_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +HooksCallback +------------- + +Класс :class:`~callbacks.HooksCallback` наследуется от :class:`~callbacks.Callback` и предназначен для добавления пользовательских хуков к модулям модели. Хуки позволяют выполнять дополнительные действия во время тренировочного процесса, такие как мониторинг активаций или изменение поведения модели. + +**Основные атрибуты:** + +- **hookfunc**: Функция, которая будет вызываться при срабатывании хука. +- **mod_filter**: Фильтр модулей, к которым будут применяться хуки. +- **on_train**: Флаг, определяющий, будет ли хук вызываться во время тренировки. +- **on_valid**: Флаг, определяющий, будет ли хук вызываться во время валидации. +- **mods**: Список модулей, к которым будут применяться хуки. Если не задан, используется `mod_filter`. + +**Основные методы:** + +- **`__init__(self, hookfunc, mod_filter=fc.noop, on_train=True, on_valid=False, mods=None)`**: Инициализирует колбек с заданными параметрами. +- **`before_fit(self, learn)`**: Добавляет хуки к указанным модулям перед началом обучения. +- **`_hookfunc(self, learn, *args, **kwargs)`**: Внутренняя функция, вызываемая хуками. +- **`after_fit(self, learn)`**: Удаляет все добавленные хуки после завершения обучения. +- **`__iter__(self)`**: Позволяет итерироваться по хукам. +- **`__len__(self)`**: Возвращает количество хуков. + +**Пример использования:** + +.. code-block:: python + + from callbacks import HooksCallback + import torch.nn as nn + + def my_hook(learn, module, input, output): + print(f"Модуль: {module}, Вход: {input}, Выход: {output}") + + hooks_cb = HooksCallback( + hookfunc=my_hook, + mod_filter=lambda m: isinstance(m, nn.Linear), + on_train=True, + on_valid=True + ) + + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[hooks_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +ActivationStats +--------------- + +Класс :class:`~callbacks.ActivationStats` наследуется от :class:`~callbacks.HooksCallback` и предназначен для сбора и визуализации статистики активаций нейронных сетей, таких как гистограммы распределения активаций и графики минимальных значений. + +**Примечание:** Класс `ActivationStats` может быть неэффективен по использованию памяти. + +**Основные атрибуты:** + +- Наследует все атрибуты от `HooksCallback`. + +**Основные методы:** + +- **`__init__(self, mod_filter=fc.noop)`**: Инициализирует колбек с заданным фильтром модулей. +- **`color_dim(self, figsize=(11, 5))`**: Визуализирует гистограммы распределения активаций. +- **`dead_chart(self, figsize=(11, 5))`**: Визуализирует графики минимальных значений активаций. +- **`plot_stats(self, figsize=(10, 4))`**: Визуализирует статистику средних значений и стандартных отклонений активаций. + +**Пример использования:** + +.. code-block:: python + + from callbacks import ActivationStats + import torch.nn as nn + + activation_stats_cb = ActivationStats(mod_filter=lambda m: isinstance(m, nn.Conv2d)) + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[activation_stats_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + + # Визуализация собранной статистики + activation_stats_cb.color_dim() + activation_stats_cb.dead_chart() + activation_stats_cb.plot_stats() + +--- + +BaseSchedCB +---------- + +Класс :class:`~callbacks.BaseSchedCB` наследуется от :class:`~callbacks.Callback` и предназначен для интеграции расписаний (schedulers) в тренировочный цикл. Он управляет шагами расписания на основе текущего состояния оптимизатора. + +**Основные атрибуты:** + +- **sched**: Расписание (scheduler), которое будет управлять оптимизатором. + +**Основные методы:** + +- **`__init__(self, sched)`**: Инициализирует колбек с заданным расписанием. +- **`before_fit(self, learn)`**: Подготавливает расписание перед началом обучения. +- **`step(self, learn)`**: Выполняет шаг расписания во время обучения. + +**Пример использования:** + +.. code-block:: python + + from callbacks import BaseSchedCB + from torch.optim.lr_scheduler import StepLR + + scheduler = StepLR(optimizer, step_size=10, gamma=0.1) + sched_cb = BaseSchedCB(sched=scheduler) + + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[sched_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=30) + +--- + +BatchSchedCB +------------ + +Класс :class:`~callbacks.BatchSchedCB` наследуется от :class:`~callbacks.BaseSchedCB` и предназначен для выполнения шагов расписания после каждого батча во время обучения. + +**Основные атрибуты:** + +- Наследует все атрибуты от `BaseSchedCB`. + +**Основные методы:** + +- **`after_batch(self, learn)`**: Выполняет шаг расписания после обработки каждого батча, если обучение активно. + +**Пример использования:** + +.. code-block:: python + + from callbacks import BatchSchedCB + from torch.optim.lr_scheduler import StepLR + + scheduler = StepLR(optimizer, step_size=100, gamma=0.1) + batch_sched_cb = BatchSchedCB(sched=scheduler) + + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[batch_sched_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +BatchTransformCB +---------------- + +Класс :class:`~callbacks.BatchTransformCB` наследуется от :class:`~callbacks.Callback` и предназначен для применения пользовательских трансформаций к каждому батчу данных перед обработкой. + +**Основные атрибуты:** + +- **tfm**: Трансформация, которая будет применяться к батчу данных. +- **on_train**: Флаг, определяющий, будет ли трансформация применяться во время тренировки. +- **on_val**: Флаг, определяющий, будет ли трансформация применяться во время валидации. + +**Основные методы:** + +- **`__init__(self, tfm, on_train=True, on_val=True)`**: Инициализирует колбек с заданной трансформацией и флагами применения. +- **`before_batch(self, learn)`**: Применяет трансформацию к текущему батчу данных, если соответствующие флаги установлены. + +**Пример использования:** + +.. code-block:: python + + from callbacks import BatchTransformCB + from torchvision import transforms + + # Определение трансформаций + data_transforms = transforms.Compose([ + transforms.RandomHorizontalFlip(), + transforms.ToTensor(), + ]) + + batch_transform_cb = BatchTransformCB(tfm=data_transforms, on_train=True, on_val=False) + + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[batch_transform_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +CapturePredsCB +------------- + +Класс :class:`~callbacks.CapturePredsCB` наследуется от :class:`~callbacks.Callback` и предназначен для захвата предсказаний модели и истинных значений (таргетов) во время обучения. Это полезно для последующего анализа или визуализации результатов. + +**Основные атрибуты:** + +- **all_preds**: Список для хранения всех предсказаний модели. +- **all_targs**: Список для хранения всех истинных значений. + +**Основные методы:** + +- **`before_fit(self, learn)`**: Инициализирует списки для хранения предсказаний и истинных значений перед началом обучения. +- **`after_batch(self, learn)`**: Добавляет предсказания и истинные значения текущего батча в соответствующие списки. + +**Пример использования:** + +.. code-block:: python + + from callbacks import CapturePredsCB + + capture_preds_cb = CapturePredsCB() + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[capture_preds_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + + # Получение всех предсказаний и истинных значений + all_preds, all_targs = capture_preds_cb.all_preds, capture_preds_cb.all_targs + +--- + +CompletionCB +------------ + +Класс :class:`~callbacks.CompletionCB` наследуется от :class:`~callbacks.Callback` и предназначен для отслеживания количества обработанных батчей и вывода сообщения о завершении обучения. + +**Основные методы:** + +- **`before_fit(self, learn)`**: Инициализирует счетчик `count` перед началом обучения. +- **`after_batch(self, learn)`**: Увеличивает счетчик `count` после обработки каждого батча. +- **`after_fit(self, learn)`**: Выводит сообщение о завершении обучения и количестве обработанных батчей. + +**Пример использования:** + +.. code-block:: python + + from callbacks import CompletionCB + + completion_cb = CompletionCB() + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[completion_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +DDPMCB +------ + +Класс :class:`~callbacks.DDPMCB` наследуется от :class:`~callbacks.Callback` и предназначен для реализации процесса шумования (noisify) и генерации выборок с использованием модели диффузии. + +**Основные атрибуты:** + +- **n_steps**: Количество шагов диффузии. +- **beta_min**: Минимальное значение бета. +- **beta_max**: Максимальное значение бета. +- **beta**: Линейно распределенные значения бета. +- **alpha**: 1 - beta. +- **alpha_bar**: Кумулятивное произведение альфа. +- **sigma**: Квадратные корни бета. + +**Основные методы:** + +- **`__init__(self, n_steps, beta_min, beta_max)`**: Инициализирует колбек с заданными параметрами. +- **`before_batch(self, learn)`**: Применяет шумование к батчу данных перед обучением. +- **`sample(self, model, sz)`**: Генерирует выборки с использованием модели и параметров диффузии. + +**Пример использования:** + +.. code-block:: python + + from callbacks import DDPMCB + + ddpm_cb = DDPMCB(n_steps=1000, beta_min=0.0001, beta_max=0.02) + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[ddpm_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +DDPMCB2 +------- + +Класс :class:`~callbacks.DDPMCB2` наследуется от :class:`~callbacks.Callback` и предназначен для модификации предсказаний модели после выполнения предсказания. + +**Основные методы:** + +- **`after_predict(self, learn)`**: Изменяет предсказания модели, вызывая метод `sample` на предсказаниях. + +**Пример использования:** + +.. code-block:: python + + from callbacks import DDPMCB2 + + ddpm_cb2 = DDPMCB2() + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[ddpm_cb2], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +EpochSchedCB +------------ + +Класс :class:`~callbacks.EpochSchedCB` наследуется от :class:`~callbacks.BaseSchedCB` и предназначен для выполнения шагов расписания после каждой эпохи во время обучения. + +**Основные методы:** + +- **`after_epoch(self, learn)`**: Выполняет шаг расписания после завершения каждой эпохи. + +**Пример использования:** + +.. code-block:: python + + from callbacks import EpochSchedCB + from torch.optim.lr_scheduler import StepLR + + scheduler = StepLR(optimizer, step_size=10, gamma=0.1) + epoch_sched_cb = EpochSchedCB(sched=scheduler) + + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[epoch_sched_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=30) + +--- + +HasLearnCB +---------- + +Класс :class:`~callbacks.HasLearnCB` наследуется от :class:`~callbacks.Callback` и предназначен для сохранения ссылки на объект `learn` во время обучения, что может быть полезно для доступа к нему в других колбеках. + +**Основные методы:** + +- **`before_fit(self, learn)`**: Сохраняет ссылку на объект `learn` перед началом обучения. +- **`after_fit(self, learn)`**: Удаляет ссылку на объект `learn` после завершения обучения. + +**Пример использования:** + +.. code-block:: python + + from callbacks import HasLearnCB + + has_learn_cb = HasLearnCB() + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[has_learn_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + + # Доступ к объекту learn + some_function(has_learn_cb.learn) + +--- + +ImageLogCB +---------- + +Класс :class:`~callbacks.ImageLogCB` наследуется от :class:`~callbacks.Callback` и предназначен для логирования изображений на определённых интервалах во время обучения. + +**Основные атрибуты:** + +- **log_every**: Интервал (в батчах) для логирования изображений. +- **images**: Список для хранения логированных изображений. +- **i**: Счетчик обработанных батчей. + +**Основные методы:** + +- **`__init__(self, log_every=10)`**: Инициализирует колбек с заданным интервалом логирования. +- **`after_batch(self, learn)`**: Логирует изображение, если достигнут заданный интервал. +- **`after_fit(self, learn)`**: Отображает все логированные изображения после завершения обучения. + +**Пример использования:** + +.. code-block:: python + + from callbacks import ImageLogCB + + image_log_cb = ImageLogCB(log_every=10) + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[image_log_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +ImageOptCB +---------- + +Класс :class:`~callbacks.ImageOptCB` наследуется от :class:`~callbacks.TrainCB` и предназначен для оптимизации предсказаний модели без дополнительных параметров. + +**Основные методы:** + +- **`predict(self, learn)`**: Выполняет предсказание модели без передачи дополнительных входных данных. +- **`get_loss(self, learn)`**: Вычисляет функцию потерь, используя предсказания модели. + +**Пример использования:** + +.. code-block:: python + + from callbacks import ImageOptCB + + image_opt_cb = ImageOptCB() + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[image_opt_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +LRFinderCB +--------- + +Класс :class:`~callbacks.LRFinderCB` наследуется от :class:`~callbacks.Callback` и предназначен для поиска оптимальной скорости обучения (learning rate) с использованием метода поиска скорости обучения. + +**Основые атрибуты:** + +- **gamma**: Коэффициент увеличения скорости обучения на каждом шаге. +- **max_mult**: Максимальный множитель для предотвращения слишком большого увеличения скорости обучения. +- **sched**: Расписание (scheduler) для управления скоростью обучения. +- **lrs**: Список для хранения скоростей обучения. +- **losses**: Список для хранения значений функции потерь. +- **min**: Минимальное значение функции потерь. + +**Основые методы:** + +- **`__init__(self, gamma=1.3, max_mult=3)`**: Инициализирует колбек с заданными параметрами. +- **`before_fit(self, learn)`**: Инициализирует расписание и списки для логирования перед началом обучения. +- **`after_batch(self, learn)`**: Логирует текущую скорость обучения и значение функции потерь, а также проверяет условия остановки поиска скорости обучения. +- **`cleanup_fit(self, learn)`**: Отображает график зависимости функции потерь от скорости обучения после завершения поиска. + +**Пример использования:** + +.. code-block:: python + + from callbacks import LRFinderCB + + lr_finder_cb = LRFinderCB(gamma=1.3, max_mult=3) + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[lr_finder_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +MetricsCB +--------- + +Класс :class:`~callbacks.MetricsCB` наследуется от :class:`~callbacks.Callback` и предназначен для вычисления и логирования различных метрик во время обучения и валидации. + +**Основные атрибуты:** + +- **metrics**: Словарь метрик, которые будут вычисляться. +- **all_metrics**: Копия словаря метрик для хранения накопленных значений. + +**Основные методы:** + +- **`__init__(self, *ms, **metrics)`**: Инициализирует колбек с заданными метриками. +- **`_log(self, d)`**: Выводит лог данных. +- **`before_fit(self, learn)`**: Устанавливает текущий объект метрик в объект `learn`. +- **`before_epoch(self, learn)`**: Сбрасывает значения всех метрик перед началом новой эпохи. +- **`after_epoch(self, learn)`**: Вычисляет и логирует средние значения метрик после завершения эпохи. +- **`after_batch(self, learn)`**: Обновляет значения метрик после обработки каждого батча. + +**Пример использования:** + +.. code-block:: python + + from callbacks import MetricsCB + from torcheval.metrics import Mean + + metrics_cb = MetricsCB(accuracy=Mean()) + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[metrics_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +MixedPrecisionCB +--------------- + +Класс :class:`~callbacks.MixedPrecisionCB` наследуется от :class:`~callbacks.TrainCB` и предназначен для использования смешанной точности (mixed precision) при обучении модели, что позволяет ускорить обучение и снизить потребление памяти. + +**Основые атрибуты:** + +- **order**: Определяет порядок выполнения колбека относительно других колбеков. Устанавливается как `DeviceCB.order + 10`. + +**Основые методы:** + +- **`__init__(self, n_inp=1, mixed_precision="fp16")`**: Инициализирует колбек с заданным количеством входных данных и типом смешанной точности. +- **`before_fit(self, learn)`**: Инициализирует `GradScaler` для масштабирования градиентов перед началом обучения. +- **`before_batch(self, learn)`**: Включает автоматическое смешанное точность перед обработкой батча. +- **`after_loss(self, learn)`**: Выключает автоматическое смешанное точность после вычисления потерь. +- **`backward(self, learn)`**: Выполняет обратное распространение ошибки с использованием `GradScaler`. +- **`step(self, learn)`**: Выполняет шаг оптимизатора с использованием `GradScaler` и обновляет масштабирование градиентов. + +**Пример использования:** + +.. code-block:: python + + from callbacks import MixedPrecisionCB + + mixed_precision_cb = MixedPrecisionCB(n_inp=1, mixed_precision="fp16") + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[mixed_precision_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +MultiGPUsCallback +----------------- + +Класс :class:`~callbacks.MultiGPUsCallback` наследуется от :class:`~callbacks.DeviceCB` и предназначен для автоматического использования нескольких GPU при доступности, что позволяет ускорить процесс обучения моделей. + +**Основые методы:** + +- **`__init__(self)`**: Инициализирует колбек, определяя устройство (GPU или CPU). +- **`before_fit(self, learn)`**: Если доступно несколько GPU, преобразует модель в `nn.DataParallel` для использования нескольких устройств, затем вызывает метод `before_fit` базового класса. +- **`after_fit(self, learn)`**: Удаляет обертку `nn.DataParallel` после завершения обучения, возвращая модель к исходному состоянию. + +**Пример использования:** + +.. code-block:: python + + from callbacks import MultiGPUsCallback + + multi_gpus_cb = MultiGPUsCallback() + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[multi_gpus_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +ProgressCB +---------- + +Класс :class:`~callbacks.ProgressCB` наследуется от :class:`~callbacks.Callback` и предназначен для отображения прогресса обучения с помощью библиотеки `fastprogress`. + +**Основые атрибуты:** + +- **plot**: Флаг, определяющий, будет ли отображаться график потерь во время обучения. +- **mbar**: Объект `master_bar` для отображения прогресса обучения. +- **first**: Флаг, определяющий, выводился ли уже заголовок таблицы метрик. +- **losses**: Список для хранения значений потерь на тренировочных данных. +- **val_losses**: Список для хранения значений потерь на валидационных данных. + +**Основые методы:** + +- **`__init__(self, plot=False)`**: Инициализирует колбек с заданным флагом отображения графика. +- **`before_fit(self, learn)`**: Инициализирует `master_bar` и настраивает логирование метрик. +- **`_log(self, d)`**: Выводит лог данных в `master_bar`. +- **`before_epoch(self, learn)`**: Инициализирует прогресс-бар для текущей эпохи. +- **`after_batch(self, learn)`**: Обновляет комментарий прогресс-бара с текущим значением потерь и обновляет график, если включено. +- **`after_epoch(self, learn)`**: Обновляет график потерь после завершения эпохи, если включено. + +**Пример использования:** + +.. code-block:: python + + from callbacks import ProgressCB + + progress_cb = ProgressCB(plot=True) + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[progress_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + +--- + +RecorderCB +--------- + +Класс :class:`~callbacks.RecorderCB` наследуется от :class:`~callbacks.Callback` и предназначен для записи и последующей визуализации различных параметров или метрик во время обучения. + +**Основые атрибуты:** + +- **d**: Словарь функций или параметров, которые будут записываться. + +**Основые методы:** + +- **`__init__(self, **d)`**: Инициализирует колбек с заданными параметрами для записи. +- **`before_fit(self, learn)`**: Инициализирует словарь записей для каждого параметра. +- **`after_batch(self, learn)`**: Добавляет текущие значения параметров в соответствующие списки. +- **`plot(self)`**: Отображает графики записанных параметров. + +**Пример использования:** + +.. code-block:: python + + from callbacks import RecorderCB + + recorder_cb = RecorderCB(loss=lambda cb: cb.learn.loss.item(), lr=lambda cb: cb.learn.opt.param_groups[0]['lr']) + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[recorder_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) + + # Визуализация записанных параметров + recorder_cb.plot() + +--- + +SingleBatchCB +------------- + +Класс :class:`~callbacks.SingleBatchCB` наследуется от :class:`~callbacks.Callback` и предназначен для остановки обучения после обработки первого батча. Это может быть полезно для тестирования или отладки модели. + +**Основые атрибуты:** + +- **order**: Определяет порядок выполнения колбека относительно других колбеков. Устанавливается как `1`. + +**Основые методы:** + +- **`after_batch(self, learn)`**: Вызывает исключение `CancelFitException` после обработки первого батча, что приводит к остановке обучения. + +**Пример использования:** + +.. code-block:: python + + from callbacks import SingleBatchCB + + single_batch_cb = SingleBatchCB() + learner = Learner( + model=model, + optimizer=optimizer, + callbacks=[single_batch_cb], + dataloaders=(train_dataloader, valid_dataloader) + ) + learner.fit(epochs=10) # Обучение остановится после первого батча + +--- + +with_cbs +-------- + +Класс-декоратор :class:`~callbacks.with_cbs` предназначен для обёртывания методов класса `Learner` с целью автоматического вызова соответствующих методов колбеков перед и после выполнения метода. + +**Основые атрибуты:** + +- **nm**: Имя метода, к которому применяется декоратор. + +**Основые методы:** + +- **`__init__(self, nm)`**: Инициализирует декоратор с заданным именем метода. +- **`__call__(self, f)`**: Оборачивает функцию `f`, добавляя вызовы колбеков до и после её выполнения, а также обработку исключений. + +**Пример использования:** + +.. code-block:: python + + from callbacks import with_cbs + + @with_cbs('fit') + def fit(self, *args, **kwargs): + # Реализация метода fit + pass + +--- \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..0f3f7f2 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,45 @@ +import os +import sys +sys.path.insert(0, os.path.abspath('../..')) +project = 'Diffusion' +copyright = '2024, Kirill Borodin' +author = 'Kirill Borodin' +release = '1.04.2004' + + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx_autodoc_typehints', + 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', + 'sphinx.ext.autosummary', +] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +autosummary_generate = True + +language = 'ru' + +autodoc_default_options = { + 'members': True, # Документировать членов (классы, методы и т.д.) + 'undoc-members': True, # Включать не документированные члены + 'private-members': False, # Исключать приватные члены (начинающиеся с _) + 'show-inheritance': True, # Показывать наследование классов +} + +html_theme = 'sphinx_rtd_theme' + +html_static_path = ['_static'] +html_css_files = [ + 'custom.css', +] +html_theme_options = { + 'navigation_depth': 4, + 'collapse_navigation': False, + 'display_version': True, + 'sticky_navigation': True, +} +autodoc_typehints = 'description' \ No newline at end of file diff --git a/docs/source/datautils.rst b/docs/source/datautils.rst new file mode 100644 index 0000000..51d7a7c --- /dev/null +++ b/docs/source/datautils.rst @@ -0,0 +1,332 @@ +Data Utilities +============= + +Утилиты для работы с данными, облегчающие обработку, загрузку и предобработку данных в библиотеке **Diffusion**. + +.. toctree:: + :maxdepth: 2 + :caption: Содержание + + collate_dict + dataloaders + random_copy + random_erase + +Collate Dictionary Functions +---------------------------- + +.. function:: collate_dict(dataset: Dataset) -> Callable + + Объединяет батчи данных в формате словаря. + + :param dataset: Набор данных, содержащий определенные особенности (features), которые необходимо объединить. + :type dataset: Dataset + :return: Функция, принимающая список элементов батча и возвращающая объединенный словарь. + :rtype: Callable + + **Пример использования:** + + .. code-block:: python + + from data_utils.collate_dict import collate_dict + from datasets import Dataset + from torch.utils.data import DataLoader + + # Инициализация набора данных + dataset = Dataset(...) + + # Создание функции объединения батчей + collate_fn = collate_dict(dataset) + + # Создание загрузчика данных с использованием функции объединения + data_loader = DataLoader(dataset, batch_size=32, collate_fn=collate_fn) + + +.. function:: collate_ddpm(b, alphabar=None, xl=None) -> Any + + Объединяет батч данных и добавляет шум для моделей DDPM. + + :param b: Батч данных. + :type b: List + :param alphabar: Параметр, определяющий уровень добавляемого шума. По умолчанию `None`. + :type alphabar: float, опционально + :param xl: Ключ для доступа к определенному элементу в батче данных. По умолчанию `None`. + :type xl: str, опционально + :return: Результат применения функции `noisify` к объединенному батчу данных. + :rtype: Any + + **Пример использования:** + + .. code-block:: python + + from data_utils.collate_dict import collate_ddpm + from torch.utils.data import DataLoader + + # Создание загрузчика данных с добавлением шума + data_loader = DataLoader( + dataset, + batch_size=32, + collate_fn=lambda b: collate_ddpm(b, alphabar=0.5, xl='data') + ) + + +.. function:: dl_ddpm(ds, bs=None, collate_fn=None, nw=None) -> DataLoader + + Создает загрузчик данных (`DataLoader`) для моделей DDPM с указанными параметрами. + + :param ds: Набор данных. + :type ds: Dataset + :param bs: Размер батча. По умолчанию `None`, что использует значение по умолчанию в `DataLoader`. + :type bs: int, опционально + :param collate_fn: Функция для объединения батча. По умолчанию `None`, что использует `default_collate`. + :type collate_fn: Callable, опционально + :param nw: Количество рабочих процессов для загрузки данных. По умолчанию `None`, что использует значение по умолчанию в `DataLoader`. + :type nw: int, опционально + :return: Объект загрузчика данных с заданными параметрами. + :rtype: DataLoader + + **Пример использования:** + + .. code-block:: python + + from data_utils.collate_dict import dl_ddpm, collate_ddpm + from torch.utils.data import DataLoader + + # Создание загрузчика данных с использованием dl_ddpm + data_loader = dl_ddpm( + ds=dataset, + bs=32, + collate_fn=lambda b: collate_ddpm(b, alphabar=0.5, xl='data'), + nw=4 + ) + +DataLoaders Classes +------------------- + +.. class:: DataLoaders(*dataloaders) + + Класс `DataLoaders` предназначен для хранения и управления несколькими загрузчиками данных, такими как тренировочный и валидационный. + + :param \*dataloaders: Загрузчики данных. Ожидается, что первыми двумя будут тренировочный и валидационный загрузчики. + :type \*dataloaders: DataLoader + + **Пример использования:** + + .. code-block:: python + + from data_utils.dataloaders import DataLoaders + from torch.utils.data import DataLoader + + train_loader = DataLoader(train_dataset, batch_size=32, collate_fn=collate_fn) + valid_loader = DataLoader(valid_dataset, batch_size=32, collate_fn=collate_fn) + + data_loaders = DataLoaders(train_loader, valid_loader) + + +.. class:: DataLoaders.from_dd(dataset_dict: dict, batch_size: int, num_workers: int, as_tuple: bool=True) -> 'DataLoaders' + + Создает экземпляр `DataLoaders` из словаря наборов данных, автоматически создавая соответствующие `DataLoader` объекты. + + :param dataset_dict: Словарь наборов данных, где ключи — названия (например, 'train', 'valid'), а значения — объекты `Dataset`. + :type dataset_dict: dict + :param batch_size: Размер батча для всех загрузчиков данных. + :type batch_size: int + :param num_workers: Количество рабочих процессов для загрузки данных. + :type num_workers: int + :param as_tuple: Если `True`, возвращает загрузчики данных как кортеж. По умолчанию `True`. + :type as_tuple: bool, опционально + :return: Экземпляр `DataLoaders` с созданными загрузчиками данных. + :rtype: DataLoaders + + **Пример использования:** + + .. code-block:: python + + from data_utils.dataloaders import DataLoaders + from data_utils.collate_dict import collate_dict + from torch.utils.data import Dataset + + dataset_dict = { + 'train': train_dataset, + 'valid': valid_dataset + } + + data_loaders = DataLoaders.from_dd( + dataset_dict=dataset_dict, + batch_size=32, + num_workers=4 + ) + + +.. class:: MultDL(dl: DataLoader, mult: int=2) + + Класс `MultDL` позволяет многократно итеративно проходить по одному и тому же загрузчику данных, умножая его длину. + + :param dl: Исходный загрузчик данных. + :type dl: DataLoader + :param mult: Множитель длины загрузчика данных. По умолчанию `2`. + :type mult: int, опционально + + **Методы:** + + .. method:: __len__() + + Возвращает удвоенную длину исходного загрузчика данных. + + :return: Удвоенная длина загрузчика данных. + :rtype: int + + .. method:: __iter__() + + Итератор, который многократно проходит по элементам исходного загрузчика данных. + + :yield: Элементы из исходного загрузчика данных. + :rtype: Iterator + + **Пример использования:** + + .. code-block:: python + + from data_utils.dataloaders import MultDL + from torch.utils.data import DataLoader + + original_loader = DataLoader(dataset, batch_size=32, collate_fn=collate_fn) + mult_loader = MultDL(original_loader, mult=3) + + for batch in mult_loader: + # Обработка батча + pass + + +Random Copy Functions and Classes +--------------------------------- + +.. function:: random_copy(x, pct=0.2, max_num=4) -> Tensor + + Добавляет случайные копии области изображения для увеличения данных. + + :param x: Входные данные в виде тензора. + :type x: Tensor + :param pct: Процент размера области, которую нужно скопировать. По умолчанию `0.2`. + :type pct: float, опционально + :param max_num: Максимальное количество копий, которые будут добавлены. По умолчанию `4`. + :type max_num: int, опционально + :return: Тензор с добавленными случайными копиями областей. + :rtype: Tensor + + **Пример использования:** + + .. code-block:: python + + from data_utils.random_copy import random_copy + import torch + + # Пример тензора изображений (N, C, H, W) + x = torch.randn(8, 3, 64, 64) + + # Добавление случайных копий + x_augmented = random_copy(x, pct=0.2, max_num=4) + + +.. class:: RandCopy(pct=0.2, max_num=4) + + Модуль PyTorch для добавления случайных копий области изображения в процессе обучения. + + :param pct: Процент размера области, которую нужно скопировать. По умолчанию `0.2`. + :type pct: float, опционально + :param max_num: Максимальное количество копий, которые будут добавлены. По умолчанию `4`. + :type max_num: int, опционально + + **Методы:** + + .. method:: forward(x: Tensor) -> Tensor + + Выполняет добавление случайных копий областей изображения. + + :param x: Входные данные в виде тензора. + :type x: Tensor + :return: Тензор с добавленными случайными копиями областей. + :rtype: Tensor + + **Пример использования:** + + .. code-block:: python + + from data_utils.random_copy import RandCopy + import torch + + # Инициализация модуля + rand_copy = RandCopy(pct=0.2, max_num=4) + + # Пример тензора изображений (N, C, H, W) + x = torch.randn(8, 3, 64, 64) + + # Применение модуля + x_augmented = rand_copy(x) + + +Random Erase Functions and Classes +---------------------------------- + +.. function:: rand_erase(x, pct=0.2, max_num=4) -> Tensor + + Выполняет случайное стирание (замену) областей изображения для увеличения данных. + + :param x: Входные данные в виде тензора. + :type x: Tensor + :param pct: Процент размера области, которую нужно стереть. По умолчанию `0.2`. + :type pct: float, опционально + :param max_num: Максимальное количество стираний, которые будут выполнены. По умолчанию `4`. + :type max_num: int, опционально + :return: Тензор с выполненными случайными стираниями областей. + :rtype: Tensor + + **Пример использования:** + + .. code-block:: python + + from data_utils.random_erase import rand_erase + import torch + + # Пример тензора изображений (N, C, H, W) + x = torch.randn(8, 3, 64, 64) + + # Выполнение случайного стирания + x_augmented = rand_erase(x, pct=0.2, max_num=4) + + +.. class:: RandErase(pct=0.2, max_num=4) + + Модуль PyTorch для выполнения случайного стирания областей изображения в процессе обучения. + + :param pct: Процент размера области, которую нужно стереть. По умолчанию `0.2`. + :type pct: float, опционально + :param max_num: Максимальное количество стираний, которые будут выполнены. По умолчанию `4`. + :type max_num: int, опционально + + **Методы:** + + .. method:: forward(x: Tensor) -> Tensor + + Выполняет случайное стирание областей изображения. + + :param x: Входные данные в виде тензора. + :type x: Tensor + :return: Тензор с выполненными случайными стираниями областей. + :rtype: Tensor + + **Пример использования:** + + .. code-block:: python + + from data_utils.random_erase import RandErase + import torch + + # Инициализация модуля + rand_erase = RandErase(pct=0.2, max_num=4) + + # Пример тензора изображений (N, C, H, W) + x = torch.randn(8, 3, 64, 64) + + # Применение модуля + x_augmented = rand_erase(x) \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..0d9aaea --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,22 @@ +Welcome to Diffusion by Me +========================== + +**Diffusion** — это библиотека искусственного интеллекта, предназначенная для облегчения разработки и внедрения моделей на основе диффузии. Библиотека предоставляет набор инструментов и утилит, которые упрощают создание, обучение и оценку моделей для различных приложений в области искусственного интеллекта. + +С Diffusion вы можете: +- Быстро создавать и настраивать модели диффузии. +- Эффективно обрабатывать и анализировать данные. +- Отслеживать метрики и улучшать производительность ваших моделей. +- Использовать готовые модули и компоненты для ускорения разработки. + +Библиотека разработана с учётом гибкости и расширяемости, что позволяет легко интегрировать её в существующие проекты и адаптировать под специфические требования. + +.. toctree:: + :maxdepth: 2 + :caption: Содержание + + callbacks + datautils + learners + metrics + modules diff --git a/docs/source/learners.rst b/docs/source/learners.rst new file mode 100644 index 0000000..309cced --- /dev/null +++ b/docs/source/learners.rst @@ -0,0 +1,307 @@ +Learners +======== + +Классы для управления процессом обучения моделей в библиотеке **Diffusion**. Эти классы обеспечивают гибкость и расширяемость тренировочного цикла, позволяя легко добавлять новые функции и изменять поведение обучения. + +.. toctree:: + :maxdepth: 2 + :caption: Содержание + + learner + train_learner + momentum_learner + + + +Learner +-------- + +:class: Learner(model, dls=(0,), loss_func=F.mse_loss, lr=0.1, cbs=None, opt_func=optim.SGD) + + Базовый класс для управления процессом обучения модели. + + :param model: Модель, которую необходимо обучать. + :type model: torch.nn.Module + :param dls: Загрузчики данных для обучения и валидации. По умолчанию `(0,)`. + :type dls: tuple, опционально + :param loss_func: Функция потерь. По умолчанию `torch.nn.functional.mse_loss`. + :type loss_func: callable, опционально + :param lr: Начальная скорость обучения. По умолчанию `0.1`. + :type lr: float, опционально + :param cbs: Колбеки для расширения функциональности обучения. По умолчанию `None`. + :type cbs: list или None, опционально + :param opt_func: Функция оптимизатора. По умолчанию `torch.optim.SGD`. + :type opt_func: callable, опционально + + **Описание:** + + Класс `Learner` управляет процессом обучения модели, включая обработку батчей, выполнение шагов оптимизации и управление колбеками. Он обеспечивает базовую структуру для реализации различных стратегий обучения. + + **Методы:** + + .. method:: fit(n_epochs=1, train=True, valid=True, cbs=None, lr=None) + + Запускает процесс обучения модели. + + :param n_epochs: Количество эпох обучения. По умолчанию `1`. + :type n_epochs: int, опционально + :param train: Флаг для включения обучения. По умолчанию `True`. + :type train: bool, опционально + :param valid: Флаг для включения валидации. По умолчанию `True`. + :type valid: bool, опционально + :param cbs: Дополнительные колбеки для этого вызова обучения. По умолчанию `None`. + :type cbs: list или None, опционально + :param lr: Скорость обучения, переопределяющая `self.lr`. По умолчанию `None`. + :type lr: float или None, опционально + + **Пример использования:** + + .. code-block:: python + + from learners.learner import Learner + import torch.nn as nn + from torch.utils.data import DataLoader, TensorDataset + + # Инициализация модели + model = nn.Linear(10, 1) + + # Создание наборов данных + train_ds = TensorDataset(torch.randn(100, 10), torch.randn(100, 1)) + valid_ds = TensorDataset(torch.randn(20, 10), torch.randn(20, 1)) + + # Создание загрузчиков данных + train_loader = DataLoader(train_ds, batch_size=32, shuffle=True) + valid_loader = DataLoader(valid_ds, batch_size=32) + + # Инициализация Learner + learner = Learner(model=model, dls=(train_loader, valid_loader), lr=0.01) + + # Запуск обучения + learner.fit(n_epochs=5, train=True, valid=True) + + .. method:: one_epoch(training) + + Выполняет одну эпоху обучения или валидации. + + :param training: Флаг, указывающий, выполняется ли обучение (`True`) или валидация (`False`). + :type training: bool + + **Пример использования:** + + .. code-block:: python + + # Выполнение одной эпохи обучения + learner.one_epoch(training=True) + + # Выполнение одной эпохи валидации + learner.one_epoch(training=False) + + .. method:: callback(method_nm) + + Выполняет метод колбека с указанным именем. + + :param method_nm: Имя метода колбека, который необходимо выполнить. + :type method_nm: str + + .. method:: __getattr__(name) + + Перенаправляет вызовы методов `predict`, `get_loss`, `backward`, `step`, `zero_grad` к соответствующим колбекам. + + :param name: Имя атрибута. + :type name: str + + .. property:: training + + Возвращает состояние модели: обучается (`True`) или нет (`False`). + + :rtype: bool + + **Пример использования колбека:** + + .. code-block:: python + + from callbacks import Callback + + class PrintCallback(Callback): + def before_fit(self, learn): + print("Начало обучения") + + def after_fit(self, learn): + print("Обучение завершено") + + # Инициализация Learner с колбеком + learner = Learner(model, dls=(train_loader, valid_loader), cbs=[PrintCallback()]) + learner.fit(n_epochs=3) + +--- + +TrainLearner +-------- +:class: TrainLearner(model, dls, loss_func, lr=None, cbs=None, opt_func=optim.SGD) + + Класс `TrainLearner` наследуется от `Learner` и реализует основные методы для выполнения предсказаний, вычисления потерь и обратного распространения ошибки. + + :param model: Модель, которую необходимо обучать. + :type model: torch.nn.Module + :param dls: Загрузчики данных для обучения и валидации. + :type dls: tuple или dict + :param loss_func: Функция потерь. + :type loss_func: callable + :param lr: Скорость обучения. По умолчанию используется значение из `Learner`. + :type lr: float, опционально + :param cbs: Колбеки для расширения функциональности обучения. По умолчанию `None`. + :type cbs: list или None, опционально + :param opt_func: Функция оптимизатора. По умолчанию `torch.optim.SGD`. + :type opt_func: callable, опционально + + **Описание:** + + `TrainLearner` реализует конкретные методы для выполнения предсказаний модели, вычисления функции потерь, обратного распространения ошибки и обновления параметров оптимизатора. + + **Методы:** + + .. method:: predict() + + Выполняет предсказание модели на текущем батче данных. + + **Пример использования:** + + .. code-block:: python + + learner.predict() + + .. method:: get_loss() + + Вычисляет функцию потерь на основе предсказаний модели и истинных значений. + + **Пример использования:** + + .. code-block:: python + + learner.get_loss() + + .. method:: backward() + + Выполняет обратное распространение ошибки для вычисленной функции потерь. + + **Пример использования:** + + .. code-block:: python + + learner.backward() + + .. method:: step() + + Обновляет параметры оптимизатора на основе вычисленных градиентов. + + **Пример использования:** + + .. code-block:: python + + learner.step() + + .. method:: zero_grad() + + Обнуляет градиенты оптимизатора перед новым шагом обучения. + + **Пример использования:** + + .. code-block:: python + + learner.zero_grad() + + **Пример использования `TrainLearner`:** + + .. code-block:: python + + from learners.train_learner import TrainLearner + import torch.nn as nn + from torch.utils.data import DataLoader, TensorDataset + + # Инициализация модели + model = nn.Linear(10, 1) + + # Создание наборов данных + train_ds = TensorDataset(torch.randn(100, 10), torch.randn(100, 1)) + valid_ds = TensorDataset(torch.randn(20, 10), torch.randn(20, 1)) + + # Создание загрузчиков данных + train_loader = DataLoader(train_ds, batch_size=32, shuffle=True) + valid_loader = DataLoader(valid_ds, batch_size=32) + + # Инициализация TrainLearner + learner = TrainLearner(model=model, dls=(train_loader, valid_loader), loss_func=nn.MSELoss(), lr=0.01) + + # Запуск обучения + learner.fit(n_epochs=5, train=True, valid=True) + +--- + +MomentumLearner +-------- + +:class: MomentumLearner(model, dls, loss_func, lr=None, cbs=None, opt_func=optim.SGD, mom=0.85) + + Класс `MomentumLearner` наследуется от `TrainLearner` и добавляет поддержку момента при обновлении градиентов. + + :param model: Модель, которую необходимо обучать. + :type model: torch.nn.Module + :param dls: Загрузчики данных для обучения и валидации. + :type dls: tuple или dict + :param loss_func: Функция потерь. + :type loss_func: callable + :param lr: Скорость обучения. По умолчанию используется значение из `TrainLearner`. + :type lr: float, опционально + :param cbs: Колбеки для расширения функциональности обучения. По умолчанию `None`. + :type cbs: list или None, опционально + :param opt_func: Функция оптимизатора. По умолчанию `torch.optim.SGD`. + :type opt_func: callable, опционально + :param mom: Коэффициент момента. По умолчанию `0.85`. + :type mom: float, опционально + + **Описание:** + + `MomentumLearner` расширяет функциональность `TrainLearner`, добавляя момент при обновлении градиентов оптимизатора. Это помогает ускорить сходимость обучения и стабилизировать процесс оптимизации. + + **Методы:** + + .. method:: zero_grad() + + Обнуляет градиенты оптимизатора, умножая их на коэффициент момента, вместо полного обнуления. Это сохраняет часть градиентов из предыдущих шагов, способствуя более стабильному обучению. + + **Пример использования:** + + .. code-block:: python + + learner.zero_grad() + + **Пример использования `MomentumLearner`:** + + .. code-block:: python + + from learners.momentum_learner import MomentumLearner + import torch.nn as nn + from torch.utils.data import DataLoader, TensorDataset + + # Инициализация модели + model = nn.Linear(10, 1) + + # Создание наборов данных + train_ds = TensorDataset(torch.randn(100, 10), torch.randn(100, 1)) + valid_ds = TensorDataset(torch.randn(20, 10), torch.randn(20, 1)) + + # Создание загрузчиков данных + train_loader = DataLoader(train_ds, batch_size=32, shuffle=True) + valid_loader = DataLoader(valid_ds, batch_size=32) + + # Инициализация MomentumLearner с моментом 0.9 + learner = MomentumLearner( + model=model, + dls=(train_loader, valid_loader), + loss_func=nn.MSELoss(), + lr=0.01, + mom=0.9 + ) + + # Запуск обучения + learner.fit(n_epochs=5, train=True, valid=True) \ No newline at end of file diff --git a/docs/source/metrics.rst b/docs/source/metrics.rst new file mode 100644 index 0000000..5380acc --- /dev/null +++ b/docs/source/metrics.rst @@ -0,0 +1,153 @@ +Metrics +======= + +Модули для работы с метриками в библиотеке **Diffusion**. Содержит реализации стандартных метрик для оценки моделей, а также инструменты для расчёта FID и KID для изображений. + +.. toctree:: + :maxdepth: 2 + :caption: Содержание + + Metric + Accuracy + ImageEval + +Metric +------ + + :class: Metric + + Базовый класс для создания метрик. + + **Описание:** + + `Metric` предоставляет интерфейс для создания пользовательских метрик. Вы можете наследоваться от этого класса и переопределять метод `calc` для реализации своей логики расчёта метрик. + + **Методы:** + + .. method:: reset() + + Сбрасывает внутренние значения метрики. Полезно для начала расчётов заново. + + **Пример использования:** + + .. code-block:: python + + metric = Metric() + metric.reset() + + .. method:: add(inp, targ=None, n=1) + + Добавляет значение метрики на основе входных данных. + + :param inp: Предсказания модели. + :type inp: tensor + :param targ: Истинные значения (по умолчанию `None`). + :type targ: tensor, опционально + :param n: Вес метрики (например, размер батча). + :type n: int + + **Пример использования:** + + .. code-block:: python + + metric.add(predictions, targets, n=batch_size) + + .. property:: value + + Возвращает текущее значение метрики. + + **Пример использования:** + + .. code-block:: python + + current_value = metric.value + + .. method:: calc(inps, targs) + + Метод расчёта значения метрики. Переопределите этот метод в подклассах для реализации пользовательской логики. + +Accuracy +-------- + + :class: Accuracy(Metric) + + Класс для вычисления точности (accuracy). + + **Описание:** + + `Accuracy` наследуется от `Metric` и реализует метод `calc`, который вычисляет точность как среднее значение совпадений предсказаний и целевых значений. + + **Методы:** + + .. method:: calc(inps, targs) + + Вычисляет точность (accuracy). + + :param inps: Предсказания модели. + :type inps: tensor + :param targs: Истинные значения. + :type targs: tensor + :return: Точность. + :rtype: tensor + + **Пример использования:** + + .. code-block:: python + + from metrics.accuracy import Accuracy + + accuracy = Accuracy() + acc_value = accuracy.calc(predictions, targets) + +ImageEval +--------- + + :class: ImageEval + + Класс для расчёта метрик FID и KID для изображений. + + :param model: Обучаемая модель. + :type model: torch.nn.Module + :param dls: Загрузчики данных. + :type dls: DataLoaders + :param cbs: Колбеки для расширения функциональности. По умолчанию `None`. + :type cbs: list или None + + **Описание:** + + `ImageEval` предоставляет методы для расчёта FID (Frechet Inception Distance) и KID (Kernel Inception Distance), используемых для оценки качества генерируемых изображений. + + **Методы:** + + .. method:: fid(samp) + + Вычисляет FID для заданного набора образцов. + + :param samp: Образцы, для которых нужно рассчитать FID. + :type samp: tensor + :return: Значение FID. + :rtype: float + + **Пример использования:** + + .. code-block:: python + + from metrics.fid_kid import ImageEval + + image_eval = ImageEval(model, dls) + fid_value = image_eval.fid(samples) + + .. method:: kid(samp) + + Вычисляет KID для заданного набора образцов. + + :param samp: Образцы, для которых нужно рассчитать KID. + :type samp: tensor + :return: Значение KID. + :rtype: float + + **Пример использования:** + + .. code-block:: python + + kid_value = image_eval.kid(samples) \ No newline at end of file diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..64cb484 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,206 @@ +Modules +======= + +Модули, предоставляющие основные строительные блоки и вспомогательные функции для работы с нейронными сетями в библиотеке **Diffusion**. + +.. toctree:: + :maxdepth: 2 + :caption: Содержание + + conv + general_relu + get_model + init_ddpm + init_weights + lsuv_init + resnet + summary + +Conv +---- + +:function: conv(input_channels, output_channels, ks=3, stride=2, act=nn.ReLU, norm=None, bias=False) + + Создает свёрточный блок с возможным добавлением активации и нормализации. + + :param input_channels: Количество входных каналов. + :type input_channels: int + :param output_channels: Количество выходных каналов. + :type output_channels: int + :param ks: Размер ядра свёртки. По умолчанию `3`. + :type ks: int, опционально + :param stride: Шаг свёртки. По умолчанию `2`. + :type stride: int, опционально + :param act: Активационная функция. По умолчанию `nn.ReLU`. + :type act: callable, опционально + :param norm: Функция нормализации. По умолчанию `None`. + :type norm: callable, опционально + :param bias: Использовать ли смещение (bias). По умолчанию `False`. + :type bias: bool, опционально + :return: Последовательность (`nn.Sequential`) слоев свёртки, нормализации и активации. + :rtype: nn.Sequential + + **Пример использования:** + + .. code-block:: python + + from modules.conv import conv + import torch.nn as nn + + conv_block = conv(3, 16, ks=3, stride=1, act=nn.ReLU, norm=nn.BatchNorm2d) + +GeneralRelu +----------- + +:class: GeneralRelu(leak=None, sub=None, maxv=None) + + Расширяемая версия функции активации ReLU с дополнительными параметрами. + + :param leak: Коэффициент утечки для Leaky ReLU. Если `None`, используется стандартный ReLU. + :type leak: float, опционально + :param sub: Сдвиг (вычитание) значений после активации. По умолчанию `None`. + :type sub: float, опционально + :param maxv: Максимальное значение для обрезки (clamping). По умолчанию `None`. + :type maxv: float, опционально + + **Пример использования:** + + .. code-block:: python + + from modules.general_relu import GeneralRelu + + act = GeneralRelu(leak=0.1, sub=0.4, maxv=6.0) + +GetModel +-------- + +:function: get_model(act=nn.ReLU, nfs=None, norm=None) + + Создает модель на основе последовательности свёрточных блоков. + + :param act: Активационная функция. По умолчанию `nn.ReLU`. + :type act: callable, опционально + :param nfs: Список количества фильтров для каждого свёрточного блока. По умолчанию `[1, 8, 16, 32, 64]`. + :type nfs: list, опционально + :param norm: Функция нормализации. По умолчанию `None`. + :type norm: callable, опционально + :return: Модель `nn.Sequential`. + :rtype: nn.Sequential + + **Пример использования:** + + .. code-block:: python + + from modules.get_model import get_model + + model = get_model() + +InitDDPM +-------- + +:function: init_ddpm(model) + + Инициализирует веса модели DDPM. + + :param model: Модель DDPM. + :type model: torch.nn.Module + + **Пример использования:** + + .. code-block:: python + + from modules.init_ddpm import init_ddpm + + init_ddpm(ddpm_model) + +InitWeights +----------- + +:function: init_weights(m, leaky=0.) + + Инициализирует веса модели с использованием `kaiming_normal_`. + + :param m: Модуль для инициализации весов. + :type m: torch.nn.Module + :param leaky: Коэффициент утечки для Leaky ReLU. По умолчанию `0`. + :type leaky: float, опционально + + **Пример использования:** + + .. code-block:: python + + from modules.init_weights import init_weights + import torch.nn as nn + + model = nn.Conv2d(3, 16, kernel_size=3) + model.apply(init_weights) + +LSUVInit +-------- + +:function: lsuv_init(m, m_in, xb, model) + + Выполняет LSUV (Layer-Sequential Unit-Variance) инициализацию весов модели. + + :param m: Модуль, который нужно инициализировать. + :type m: torch.nn.Module + :param m_in: Входной модуль. + :type m_in: torch.nn.Module + :param xb: Входные данные. + :type xb: torch.Tensor + :param model: Модель для обучения. + :type model: torch.nn.Module + + **Пример использования:** + + .. code-block:: python + + from modules.lsuv_init import lsuv_init + + lsuv_init(layer, layer_input, input_batch, model) + +ResNet +------ + +:class: ResBlock(ni, nf, stride=1, ks=3, act=act_gr, norm=None) + + Реализация Residual блока. + + :param ni: Количество входных каналов. + :type ni: int + :param nf: Количество выходных каналов. + :type nf: int + :param stride: Шаг свёртки. По умолчанию `1`. + :type stride: int, опционально + :param ks: Размер ядра свёртки. По умолчанию `3`. + :type ks: int, опционально + :param act: Функция активации. По умолчанию `act_gr`. + :type act: callable, опционально + :param norm: Функция нормализации. По умолчанию `None`. + :type norm: callable, опционально + + **Пример использования:** + + .. code-block:: python + + from modules.resnet import ResBlock + + res_block = ResBlock(64, 128, stride=2) + +Summary +------- + +:function: summary(self) + + Выводит краткое описание модели, включая информацию о модулях, размерах входов и выходов, а также количестве параметров. + + :param self: Экземпляр `Learner`. + :type self: Learner + + **Пример использования:** + + .. code-block:: python + + from modules.summary import summary + + learner.summary() \ No newline at end of file diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..391fcf0 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +sphinx==5.3.0 +sphinx-autodoc-typehints==1.19.1 +sphinx-rtd-theme==1.0.0 +sphinxcontrib-napoleon==0.7 \ No newline at end of file