configuration mechanism

src/opencl/Compare.md

@@ -0,0 +1,372 @@
+# Сравнение библиотек для создания механизма конфигурирования
+Вся информация взята из репозиториев соответствующих проектов. Дата обращения: 21.04.26.
+
+## Критерии сравнения
+
+| Критерий | Метрика | Единицы измерения |
+|:---|:---|:---|
+| **Зависимости** | наличие | +/- |
+| **Источники** | CLI (argv) / env / файлы | +/-, форматы |
+| **Стандарт C++** | минимальная версия | C++хх |
+| **Поддерживает стандарт иерархии** | Linux/Windows/MacOS | +/- |
+| **Способ распространения** | header-only / статическая / динамическая | — |
+| **ОС** | Linux / Windows / macOS | +/-, компиляторы |
+| **Активность** | среднее число коммитов | коммитов/мес (за последний мес) |
+| **Issues** | open, closed/open | n, коэффициент |
+| **Сообщество** | GitHub Stars | n |
+| **Проходит ли CI** | CI | +/- |
+
+> ? - не указано в README.
+
+
+## Сравнение парсеров командной строки (CLI)
+
+| Критерий | CLI11 | cxxopts | 
+|:---|:---:|:---:|
+| Зависимости | - | - |
+| **Источники** | | |
+|  CLI (argv) | + | + | 
+|  env | + | - | 
+|  Файлы | - | - | 
+| Стандарт C++ | ≥ C++11 | ≥ C++11 | 
+| **Поддерживает стандарт иерархии** | | |
+|  Linux | + | + |
+|  Windows | + | + | 
+|  MacOS | + | + |  
+| Способ распространения | header-only | header-only 
+| **ОС** | | |
+|  Linux | + (GCC 4.8+, Clang 3.5+) | + (GCC ≥ 4.9, Clang ≥ 3.1) |
+|  Windows | + (MSVC ≥ 2015) | + (MSVC ≥ 2015) |
+|  macOS | + (AppleClang 7+) | + (Clang ≥ 3.1 с libc++) |
+| **Сообщество** | | | 
+|  Активность (коммитов/мес) | 4 | 1 |
+|  Issues всего | 506 | 307 | 
+|  Issues closed/open | 9 | 6 | 
+|  Stars | 4.3k | 4.7k | 
+| Проходит ли CI | + | + | + |
+
+
+## Парсеры файлов
+
+| Критерий | nlohmann/json  | yaml-cpp | toml++ | toml11 | config-cxx | taocpp/config
+|:---|:---:|:---:|:---:|:---:|:---:|:---:|
+| Зависимости | - | - | - | - | - | - |
+| **Источники** |
+|  CLI (argv) | - | - | - | - | - | - |
+|  env | - | - | - | - | + | + |
+|  Файлы | JSON | YAML | TOML | TOML | JSON, YAML, XML | JSON, JAXN |
+| Стандарт C++ | ≥ C++11 | ≥ C++11 | ≥ C++17 | ≥ C++11 | ≥ C++20 | ≥ C++17 |
+| **Поддерживает стандарт иерархии** |
+|  Linux | + | + | + | + | + | + |
+|  Windows | + | + | + | + | + | + |
+|  MacOS | + | + | + | + | + | + |
+| Способ распространения | header-only | статическая/динамическая¹ | header-only/статическая/динамическая¹ | header-only/статическая/динамическая¹ | header-only | header-only |
+| **ОС** | | |
+|  Linux | + (GCC 4.8–14.2, Clang 3.4–21.0) | + (GCC, Clang) | + (Clang 8+, GCC 8+) | + (GCC, Clang) | + (GCC 13+, Clang 16+) | +
+|  Windows | + (MSVC 2015–2022) | + (MSVC) | + (MSVC VS2019+) | + (MSVC, MinGW) | + (MSVC 143+ (VS 2022)) | +
+|  macOS | + (AppleClang 9.1–16.0) | + (Xcode, AppleClang) | + (AppleClang) | + (AppleClang) | + (AppleClang 16+) | +
+| **Сообщество** | | | 
+|  Активность (коммитов/мес) | 2 | 9 | 2 | 4 | 2 | 13 |
+|  Issues всего | 3271 | 905 | 193 | 194 | 24 | 5 |
+|  Issues closed/open | 68 | 3 | 8 | 5 | 0 open | 0 open |
+|  Stars | 49.4k | 15k | 2k | 1.3k | 31 | 194 |
+| Проходит ли CI | + | + | + | - | + | ? |
+
+> ¹ Опционально.
+
+## Сравнение универсальных инструментов
+
+| Критерий | Boost.Program_options
+|:---|:---:|
+| Зависимости | +¹ |
+| **Источники** | | |
+|  CLI (argv) | + | + |
+|  env | + | + |
+|  Файлы | INI |
+| Стандарт C++ | ≥ C++3 | 
+| **Поддерживает стандарт иерархии** | | |
+|  Linux | + | 
+|  Windows | + | 
+|  MacOS | + |
+| Способ распространения | статическая/динамическая² | 
+| **ОС** | | |
+|  Linux | + (GCC 5+, Clang 3.6+) | 
+|  Windows | + (MSVC 2015 (vc140)+) |
+|  macOS | + (AppleClang) |
+| **Сообщество** | | | 
+|  Активность (коммитов/мес) | 12 | 
+|  Issues всего | 400 | 
+|  Issues closed/open | 1 | 
+|  Stars | 9.4k |
+| Проходит ли CI | + | + |
+
+> ¹ Список зависимостей: 
+> 1. Boost.Any
+> 2. Boost.Bind
+> 3. Boost.Config
+> 4. Boost.Core
+> 5. Boost.Detail
+> 6. Boost.Function
+> 7. Boost.Iterator
+> 8. Boost.Lexical Cast
+> 9. Boost.Smart Ptr
+> 10. Boost.ThrowException
+> 11. Boost.Tokenizer
+> 12. Boost.Type Traits 
+
+> ² Опционально.
+
+
+## Итог:
+По результатам сравнения, вероятно, лучшим вариантом будет использование `CLI11` и `nlohmann/json`, так как они, в отличие от `Boost.program_options`, не требуют зависимостей и являются header-only.
+
+
+# Механизм конфигурирования библиотеки SPLA
+
+## МАНУАЛ:
+
+## НАЗВАНИЕ
+spla - это фреймворк для математических вычислений с использованием GPU/ускорения
+
+## СИНОПСИС
+
+```cpp
+#include <spla.hpp>
+
+
+int main(int argc, char* argv[]) {
+
+    spla_configure(argc, argv);
+
+    return 0;
+}
+```
+Функция `spla_configure(argc, argv)` необходима для обработки аргументов командной строки, переменных окружения и конфигурационных файлов.
+
+(будет написана)
+
+## ОПИСАНИЕ
+**spla** - это библиотека с открытым исходным кодом, предоставляющая примитивы разреженной линейной алгебры (матрицы, векторы, скаляры) для математических вычислений с ускорением на GPU. Библиотека поддерживает широкий спектр операций, включая умножение матрицы на вектор, решение систем линейных уравнений и другие алгоритмы разреженной алгебры.
+
+Для большинства пользователей важно, на каком ускорителе будет запускаться их проект, поэтому необходима возможность явного указания графического ускорителя, OpenCL платформы, количества очередей команд и других параметров, влияющих на производительность и удобство пользователя.
+
+<a id="configuration_methods"></a>Библиотека предоставляет механизмы конфигурирования, показанные в порядке убывания приоритета. 
+
+1. Аргументы командной строки <sup>1</sup>.
+2. Переменные окружения <sup>2</sup>.
+3. Пользовательский конфигурационный TOML/INI файл <sup>3</sup>.
+4. Системный конфигурационный TOML/INI файл <sup>3</sup>.
+
+Системный конфигурационный файл имеет наименьший приоритет. \
+Его настройки переопределяются пользовательским конфигурационным файлом, переменными окружения и аргументами командной строки.
+
+Пользовательский конфигурационный файл имеет приоритет над системным
+конфигурационным файлом. \
+Его настройки переопределяются переменными
+окружения и аргументами командной строки.
+
+Переменные окружения имеют приоритет над системным и пользовательским конфигурационными файлами, но уступают аргументам командной строки.
+
+Аргументы командной строки имеют наивысший приоритет и переопределяют любые настройки, определенные предыдущими способами.
+
+Если источника конфигурации с меньшим приоритетом не существует, библиотека игнорирует его и переходит к следующему источнику конфигурации.
+
+Библиотека требует настройки всех обязательных параметров. Без этого будет генерироваться исключение `IncompleteConfigError`.\
+Чтобы исключение не возникало, пользователь должен явно настроить все параметры любым [способом](#configuration_methods).
+
+> <sup>1</sup> Описание аргументов командной строки приведены в разделе [ПАРАМЕТРЫ КОМАНДНОЙ СТРОКИ](#options). \
+<sup>2</sup> Описание переменнных окружения приведены в разделе [ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ](#env_variables). \
+<sup>3</sup> Шаблон конфигурационного файла с описанием приведен [здесь](#config).
+
+## <a id="options"></a>ПАРАМЕТРЫ КОМАНДНОЙ СТРОКИ
+```bash
+-sh
+--spla-help
+```
+Выводит список всех доступных флагов spla с кратким описанием.
+
+```bash
+-sv
+--spla-version
+```
+Показывает номер версии spla.
+
+```bash
+-ss <путь>
+--spla-sconf <путь>
+```
+Путь к системному конфигурационному файлу. 
+
+По умолчанию ищет файл в стандартном для данной ОС месте.\
+`/etc/spla/spla.toml` на Linux. \
+`/Library/Preferences/spla/spla.toml` на macOS. \
+`%ProgramData%\spla\spla.toml` на Windows.
+
+```bash
+-su <путь>
+--spla-uconf <путь>
+```
+Путь к пользовательскому конфигурационному файлу. 
+
+По умолчанию ищет файл в стандартном для данной ОС месте. \
+`~/.config/spla/spla.toml` на Linux. \
+`~/Library/Application Support/spla/spla.toml` на macOS. \
+`%APPDATA%\spla\spla.toml` на Windows.
+
+```bash
+-sp <индекс>
+--spla-platform <индекс>
+```
+Индекс OpenCL платформы.
+
+```bash
+-sd <индекс>
+--spla-device <индекс>
+```
+Индекс OpenCL-устройства выбранной платформы (GPU/CPU).
+
+```bash
+-sq <число>
+--spla-queues <число>
+```
+Количество очередей команд.
+
+Увеличение числа очередей может повысить производительность
+за счет параллельного выполнения независимых задач, но слишком большое значение может снизить производительность из-за накладных расходов. \
+Рекомендуется начинать с 1 и экспериментально подбирать оптимальное значение.
+
+```bash 
+-sV <уровень>
+--spla-verbosity <уровень>
+```
+Уровень детализации отладочной информации, выводимой библиотекой.
+
+| Уровень | Значение | Описание |
+|:-------:|:---------|:---------|
+| **0** | OFF | Вывод отключён. Сообщения не выводятся. |
+| **1** | ERROR | Только критические ошибки. |
+| **2** | WARNING | Ошибки и предупреждения. |
+| **3** | INFO | Основные этапы работы библиотеки. |
+
+Что выводится на каждом уровне:
+
+1. ERROR — `Error`, `NoAcceleration`, `PlatformNotFound`, `DeviceNotFound`, `InvalidState`, `InvalidArgument`, `CompilationError`
+
+2. WARNING — добавляет к ERROR: `NoValue`, `NotImplemented`
+
+3. INFO — добавляет к WARNING: `Ok` - информация об инициализации, выборе платформы/устройства, загрузке конфигурации
+
+```bash 
+-sp
+--spla-profiling 
+```
+Профилирование очередей команд OpenCL.
+
+Bключение профилирования добавляет накладные расходы на каждую
+операцию и может замедлить выполнение.
+
+```bash
+-sa <тип>
+--spla-allocator <тип>
+```
+Тип аллокатора памяти для OpenCL-устройства. \
+Ожидает: lineral | general.
+
+Выбор аллокатора влияет на производительность операций с памятью.
+Линейный аллокатор даёт прирост скорости за счёт последовательного выделения,
+но может привести к фрагментации памяти при длительной работе.
+Общий аллокатор более надёжен, но медленнее.
+
+```bash
+-sS <размер>
+--spla-allocator-size <размер>
+```
+Размер линейного аллокатора в байтах.
+
+Увеличение размера позволяет выделять больше памяти за один раз, но увеличивает потребление ресурсов. \
+Этот параметр необходим только при использовании линейного аллокатора `--spla-allocator linear`. 
+При использовании общего аллокатора можно не указывать.
+
+Пример:
+```bash
+./my_program --spla-uconf ~/my_configs/spla.toml --spla-platform 1 -sd 0 --spla-verbosity 3 -sp true --spla-allocator linear --spla-allocator-size 1048576
+```
+
+## <a id="env_variables"></a>ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ
+Для всех параметров командной строки (кроме --spla-help, --spla-version) существуют аналоги в виде переменных окружения.
+
+`SPLA_SYSTEM_CONFIG_PATH` \
+Путь к системному конфигурационному файлу. Аналог параметра --spla-sconf.
+
+`SPLA_USER_CONFIG_PATH` \
+Путь к пользовательскому конфигурационному файлу. Аналог параметра --spla-uconf.
+
+`SPLA_OPENCL_PLATFORM` \
+Индекс OpenCL платформы. Аналог параметра --spla-platform.
+
+`SPLA_OPENCL_DEVICE`\
+Индекс OpenCL-устройства на выбранной платформе.
+Аналог параметра --spla-device.
+
+`SPLA_QUEUES`\
+Количество очередей команд OpenCL.
+Аналог параметра --spla-queues.
+
+`SPLA_VERBOSITY`\
+Уровень детализации отладочной информации.
+Аналог параметра --spla-verbosity.\
+Принимает значения от 0 до 3.
+
+`SPLA_PROFILING`\
+Включает профилирование очередей команд OpenCL.
+Аналог параметра --spla-profiling.
+
+`SPLA_ALLOCATOR`\
+Тип аллокатора памяти для OpenCL-устройства.
+Аналог параметра --spla-allocator.\
+Принимает значения: linear, general.
+
+`SPLA_ALLOCATOR_SIZE`\
+Размер линейного аллокатора в байтах.
+Аналог параметра --spla-allocator-size.\
+Имеет смысл только при использовании линейного аллокатора.
+
+
+## <a id="config"></a>КОНФИГУРАЦИОННЫЕ ФАЙЛЫ
+Для всех аргументов командной строки (кроме --spla-help, --spla-version, --spla-sconf, --spla-uconf) и всех переменных окружения существуют аналоги в виде параметров конфигурационного файла.
+
+Формат файла - TOML или INI. 
+
+Типы значений.
+1. platform = int
+2. device = int
+3. queues = int
+4. verbosity = int
+5. profiling = true | false
+6. allocator = linear | general
+7. allocator_size = int
+
+Примеры конфигурационных файлов.\
+Этот формат справедлив как для пользовательского, так и для системного конфигурационного файла.
+
+Формат TOML.
+```toml
+platform = 1
+device = 0
+queues = 4
+verbosity = 2
+profiling = false
+allocator = "linear"
+allocator_size = 1048576
+```
+
+Формата INI.
+```ini
+platform = 1
+device = 0
+queues = 4
+verbosity = 2
+profiling = true
+allocator = linear
+allocator_size = 1048576
+```