configuration mechanism

src/opencl/Compare.md

@@ -0,0 +1,275 @@
+# Сравнение библиотек для создания механизма конфигурирования
+Вся информация взята из репозиториев соответствующих проектов. Дата обращения: 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 требует явного конфигурирования. \
+При установке поставляется дефолтный конфиг. Для запуска программы пользователь должен передать библиотеке путь к конфигу (дефолтному или своему) и опционально — идентификатор конфигурации. Если идентификатор не указан, используется конфигурация default. Без конфига библиотека не запускается.
+
+## Пользователь, который хочет решить свою задачу, используя spla:
+### 1. Быстрая настройка основных параметров 
+
+Параметры для конфигурирования:
+1. явное указание платформы `SPLA_OPENCL_PLATFORM`
+2. явное указание устройтсва `SPLA_OPENCL_DEVICE`
+3. выбрать количество очередей `queues_count`
+4. уменьшить количество отладочной информации до минимума: оставить только критические ошибки
+
+### 2. Замер и сравнение производительности вычислений на разных GPU
+Цель пользователя: Сравнение производительности разных девайсов 
+
+Параметры для конфигурирования: 
+1. явное указание платформы
+2. явное указание устройтсва
+3. выбрать количество очередей
+4. увеличить количество отладочной информации
+5. выбор аллокатора `allocator_type`
+6. размер для линейного аллокатора `linear_allocator_size` или `block_size` и `block_count` для pool аллокатора
+6. `default_wgs`
+7. `wave_size`
+8. профайлинг очередей `CL_QUEUE_PROFILING_ENABLE`
+9. сбор статистики
+
+### 3. Отладка алгоритма GPU
+Цель пользователя: 
+1. верификация корректности работы на разных устройствах 
+2. поиск ошибок в алгоритме
+
+Параметры для конфигурирования: 
+1. явное указание платформы
+2. явное указание устройтсва
+3. выбрать количество очередей
+4. увеличить количество отладочной информации
+5. очищать кэш при запуске
+6. отключение оптимизации при компиляции
+
+
+### 4. Тестирование GPU
+Цель пользователя: 
+1. верификация корректности работы устройства
+2. поиск ошибок в устройтсве
+
+Параметры для конфигурации: 
+1. явное указание платформы
+2. явное указание устройтсва
+3. выбрать количество очередей
+4. увеличить количество отладочной информации
+
+
+
+## Разработчик spla:
+
+### 1. Бенчмаркер
+
+Цели и параметры конфигурирования аналогичны [сценарию 2](#2-замер-и-сравнение-производительности-вычислений-на-разных-gpu) 
+
+
+### 2. Отладчик, тестировик
+
+Цели и параметры конфигурирования аналогичны [сценарию 3](#3-отладка-алгоритма-gpu) 
+
+
+
+## Основные дефолтные значения
+
+платформа: первая платформа \
+девайс: первое устройство \
+queues_count = 1 \
+отладочная информация: критичнеские ошибки \
+аллокатор: general \
+default_wgs: 1\
+wave_size: 1\
+профайлинг: false
+сбор статистики: false 
+очищать кэш при запуске: false
+отключение оптимизации при компиляции: false
+
+<!-- # Что нужно конфигурировать 
+1. Выбор платформы
+2. Выбор устройства 
+3. Количество очередей: сейчас создается только 1 очередь 
+4. Приоритеты очередей
+5. Размер линейного аллокатора `DEFAULT_SIZE`
+6. Стратегия выбора аллокатора: \
+    NVIDIA используют общий аллокатор \
+    Все остальные используем линейный аллокатор
+7. Характеристики устройтсв:\
+    `m_vendor_id` \
+    `m_max_cu` \
+    `m_default_wgs` \
+    `m_max_local_mem` \
+    `m_addr_align` \
+    пороги `m_max_wgs`, `m_max_cu`, `m_wave_size`
+8. Строковые паттерны проверки девайса: возможно только 3 вариаета `m_vendor_name`
+6. Дефолтные значения характеристик \
+    `m_addr_align` \
+    `m_default_wgs` \
+    `uint m_wave_size` \
+    `uint m_num_of_mem_banks`
+7. Суффикс и имя \
+    `m_name` \
+    `m_suffix `
+8. Тип устройства (чтобы можно было использовать CPU)
+    `getDevices` -->
+
+# Структура конфига (JSON)
+
+```bash
+config:
+
+    "platform":
+        "selection":
+            "user_alias": string
+            "official_name": string
+            "vendor": "nvidia" | "amd" | "intel" | "img" | ""
+        "index": int
+        "priority": int
+        "fallback": (???)                           # Нужен ли fallback
+        "device":
+            "selection": 
+                "user_alias": string
+                "official_name": string
+                "type": "gpu" | "cpu" 
+            "index": int
+            "priority": int
+            "naming": 
+                "accelerator_name"                      # m_name
+                "cache_suffix"                          # m_suffix
+            "tuning": 
+                "default_work_group_size": int          # m_default_wgs
+                "wave_size": int                        # m_wave_size
+                "memory_banks": int                     # m_num_of_mem_banks
+                "memory_alignment": int                 # m_addr_align
+            "fallback": (???)                           # Нужен ли fallback
+            "performance"
+                "memory"
+                    "linear_allocator_size_mb": int         # DEFAULT_SIZE
+                    "allocator_strategy":   "auto" | "linear" | "general" | "vendor"
+                    "vendor_strategy":
+                        "nvidia":           "linear" | "general"
+                        "amd":              "linear" | "general"
+                        "intel":            "linear" | "general"
+                        "img":              "linear" | "general"
+            "queues": 
+                "count": int
+
+```
+