configuration mechanism

src/opencl/Compare.md

@@ -0,0 +1,352 @@
+# Сравнение библиотек для создания механизма конфигурирования
+Вся информация взята из репозиториев соответствующих проектов. Дата обращения: 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:
+## Дефолтный сценарий
+
+Дефолтный сценарий должен решать главную задачу библиотеки: ускорение вычислений.
+
+### Выбор платформы и устройства
+
+Сначала следует выбрать наиболее подходящий девайс. Для этого необходимо пройти по всем платформам, собрать все устройства каждой платформы и среди них выбрать лучший.
+
+Выбранное устройство должно удовлетворять следующим критериям:
+1. физически существовать у пользователя
+
+2. проходить базовые проверки: \
+        - запрос размера глобальной памяти \
+        - попытка выделить и освободить буфер
+
+Из всех рабочих и доступных устройств необходимо выбрать наиболее быстрое. Выбор осуществляется по следующей иерархии:
+
+1. Внешняя GPU (eGPU)
+
+2. Дискретная GPU (dGPU)
+
+3. Интегрированная GPU (iGPU)
+
+4. Запуск на CPU (при отсутствии GPU)
+
+При наличии нескольких GPU одного типа на каждом из них запускаются микробенчмарки с эталонной задачей, характерной для SPLA. В итоге выбирается GPU, показавшая лучшие результаты, и соответствующая ей платформа.
+
+Данный подход решает потенциальную проблему, когда девайс указан в OpenCL-платформе, но фактически отсутствует в системе.
+
+--
+
+Нужно ли как-то учитывать параметры платформ?
+
+Логирование: Выдавать всю информацию (какие стандарты логирования? какая иерархия ошибок?)
+
+Бенчмарки: \
+Какую задачу прогонять? \
+Как вести замеры? \
+Подбор колтчества очередей: k = (t_вычислений)/ t_общ \
+если k = 0.5 => 1 очередь \
+если k >> 0.5 => ускорять передачу данных? \
+еслм k << 0. => ускорять вычисления? 
+
+как подбирать оптимально \
+пользовательское количество потоков work group size \
+способ аллокации памяти и размер аллокатора
+
+Иерархия ошибок?
+
+### Настройка очередей команд
+
+### Логирование
+
+### Тестовые бенчмарки
+
+
+## Пользователь, который хочет решить свою задачу, используя spla:
+### 1. Быстрая настройка основных параметров 
+
+Параметры для конфигурирования:
+1. явное указание платформы
+2. явное указание устройтсва
+3. выбрать количество очередей
+4. уменьшить количество отладочной информации до минимума: оставить только критические ошибки
+5. выбор аллокатора 
+
+### 2. Замер и сравнение производительности вычислений на разных GPU
+Цель пользователя: 
+1. Минимизация шума при измерениях
+2. Воспроизводимость результатов
+3. Сравнение разных конфигураций
+
+Параметры для конфигурирования: 
+1. явное указание платформы
+2. явное указание устройтсва
+3. выбрать количество очередей
+4. **увеличить количество отладочной информации**
+5. выбор аллокатора 
+6. Wave size override
+7. Work-group size
+8. профайлинг очередей `CL_QUEUE_PROFILING_ENABLE`
+9. сбор статистики и уменьшение шума `CLCounterPool`**
+
+### 3. Отладка алгоритма GPU
+Цель пользователя: 
+1. верификация корректности работы на разных устройствах 
+2. воспроизводимость ошибок
+
+Параметры для конфигурирования: 
+
+### 4. Тестирование GPU
+Параметры для конфигурации: 
+
+### 5. Пользователь знает, что некоторые вычисления лучше считаются на GPU
+Параметры для конфигурации: 
+
+### 6. Задачи, требующие воспроизводимости
+Параметры для конфигурации: 
+
+
+
+
+# Сценарии использования spla:
+**Что важно всем:** возможность выбрать платформу и устройство 
+**Цель:**  
+1. Пользователь хочет решить свою задачу 
+    - Неподготовленный пользователь
+        - важно: 
+            - быстрая настройка через флаги
+        - что конфигурировать:
+            - уменьшить количество отладочной информации
+            - остальное - дефолтные параметры
+    - Опытный пользователь: 
+        - важно:
+            - детальная ручная конфигурация параметров через конфигурационный файл
+            - ускорение вычислений с разреженными данными
+        - что конфигурировать:
+            - управление кэшем
+            - кастомные аллокаторы для разных форматов данных
+            - управление очередями команд 
+            - Wave size override
+            - Work-group size
+            - оптимизация доступа к глобальной памяти
+            - управление логированием
+2. Разработчик spla
+    - Отладчик, тестировик
+        - важно: 
+            - верификация корректности работы на разных устройствах 
+            - воспроизводимость ошибок
+        - что конфигурировать:
+            - возможность работать только на 1 гпу
+            - подробное логирование
+            - отключение кэша для принудительной перекомпиляции
+            - тестирование на неподдерживаемых вендорах без падения с ошибкой
+    - Бенчмаркер
+        - важно:
+            - минимизация шума при измерениях
+            - воспроизводимость результатов
+            - сравнение разных конфигураций
+        - что конфигурировать:
+            - профайлинг очередей `CL_QUEUE_PROFILING_ENABLE`
+            - сбор статистики и уменьшение шума `CLCounterPool`
+            - количество очередей для измерения параллелизма
+            - линейный аллокатор для предсказуемости памяти
+            - Wave size override
+            - Work-group size
+            - оптимизация доступа к глобальной памяти
+    - Расширяющий функциональность
+        - важно: 
+            - возможность встроить код в существующую инфраструктуру
+            - чтобы новый код работал на всех устройтсвах
+        - что конфигурировать:
+            - включение кэша
+            - кастомные аллокаторы для разных форматов данных
+            - управление очередями
+            - Wave size override
+            - Work-group size
+
+# Что нужно конфигурировать 
+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
+
+```
+