Efim Beshmenev
291 lines
18 KiB
Markdown
291 lines
18 KiB
Markdown
# Szilassi — поиск геометрических реализаций многогранников
|
||
|
||
Репозиторий содержит CUDA/CPU-систему поиска геометрических реализаций для 59
|
||
комбинаторных топологий соседственных 12-гранных многогранников. Для каждой
|
||
топологии программа подбирает 12 плоскостей, восстанавливает вершины и минимизирует
|
||
геометрические дефекты.
|
||
|
||
Проект предназначен для вычислительного исследования и не является доказательством
|
||
существования или невозможности бездефектной реализации.
|
||
|
||
## Происхождение
|
||
|
||
Проект основан на исходной кодовой базе CodeParade
|
||
[HackerPoet/NeighborlyPolyhedra](https://github.com/HackerPoet/NeighborlyPolyhedra).
|
||
Постановка задачи и исходное исследование представлены в
|
||
[видео CodeParade](https://youtu.be/5dd8_N_nKRI). Текущая версия существенно
|
||
расширяет исходную реализацию: добавлены CUDA FP32-поиск, CPU/DD-верификация,
|
||
продолжаемые checkpoint, многотопологический планировщик, MAP-Elites/CEM,
|
||
нейросетевая подсказка и локальный долговременный ML-датасет.
|
||
|
||
## Критерии результата
|
||
|
||
В логах и файлах результатов используются два целочисленных счётчика:
|
||
|
||
- `C` (`crossings`) — самопересечения границы отдельной грани после проекции на
|
||
плоскость этой грани;
|
||
- `I` (`intersections`) — пересечения внутренности грани с рёбрами, которые не
|
||
инцидентны этой грани. Пересечение продолжений вне отрезка или вне многоугольника
|
||
не учитывается.
|
||
|
||
Кандидаты сравниваются лексикографически по кортежу
|
||
`(C + I, max(C, I), C, energy)`. Поэтому уменьшение точного количества дефектов
|
||
важнее гладких штрафов и эвристических оценок.
|
||
|
||
Массовый поиск выполняется на GPU в FP32. Отобранные кандидаты пересчитываются на
|
||
CPU в `double`; состояния около цели дополнительно классифицируются реализацией
|
||
double-double (`WideReal`, примерно 31 десятичный знак). Заявленный результат
|
||
`C/I = 0/0` проходит повторные проверки с несколькими допусками.
|
||
|
||
## Как устроен поиск
|
||
|
||
- Постоянные CUDA-цепочки сохраняют RNG, температуру, шаг, стагнацию и состояние
|
||
между короткими пакетами.
|
||
- Портфель стратегий включает базовый simulated annealing, replica exchange,
|
||
адаптивные ходы, population-based transfer и инъекцию состояний из MAP-Elites,
|
||
CEM и нейросетевой подсказки.
|
||
- Планировщик распределяет работу между топологиями с учётом качества,
|
||
улучшений, неопределённости и давности последнего запуска. Режим проработки
|
||
худших вариантов меняет приоритет, но сохраняет исследование остальных топологий.
|
||
- MAP-Elites поддерживает разнообразие по обусловленности геометрии и локализации
|
||
дефектов. Диагональный CEM строит новые стартовые состояния по успешным потомкам.
|
||
- Небольшой SPSA+Adam этап выполняется на CPU; его результат округляется обратно
|
||
в FP32 и проверяется заново.
|
||
- Нейросеть является только источником предложений. Она не может заменить точную
|
||
CPU/DD-проверку или отключить базовую долю независимого поиска.
|
||
|
||
Штраф вырождения намеренно мягкий. По умолчанию полностью учитывается худший из
|
||
барьеров определителя, короткого ребра, малого угла поворота и чрезмерного размера;
|
||
остальные барьеры дают по 5% вклада. Вес штрафа — `0.01`.
|
||
|
||
Поисковый процесс и CUDA stream запускаются с низким приоритетом. Искусственного
|
||
ограничения загрузки GPU нет; короткие kernels обеспечивают отзывчивую остановку
|
||
и устойчивость под Windows WDDM.
|
||
|
||
## Структура репозитория
|
||
|
||
- `projects/Szilassi` — основной CLI-поиск;
|
||
- `projects/PolyhedronGui` — Windows GUI для штатного CUDA-поиска;
|
||
- `projects/VerifyCpp` — отдельная проверка OBJ-кандидатов;
|
||
- `src/NeighborlyCore` — геометрия, точные предикаты и общие типы;
|
||
- `src/CudaSearch` — FP32 CUDA backend и диагностический CPU stub;
|
||
- `src/Checkpoint` — CRC-защищённые поколения checkpoint;
|
||
- `src/SearchArchive` — mergeable MAP-Elites delta-файлы;
|
||
- `src/OnlineSurrogate` — локальная online residual-MLP модель;
|
||
- `src/TrainingArchive` — локальный долговременный ML-датасет и crash recovery;
|
||
- `tests/TrainingArchiveSelfTest` — тест формата, CRC, WAL, восстановления и лимита;
|
||
- `data` — описание топологий и входные модели;
|
||
- `results/topologies` и `results/showcases` — сохранённые исследовательские модели;
|
||
- `results/search` — продолжаемое геометрическое состояние поиска;
|
||
- `runtime` — временные тестовые прогоны, отчёты и локальные файлы;
|
||
- `build` — централизованный вывод CMake и MSBuild.
|
||
|
||
Общего solution-файла в репозитории нет. Основной поддерживаемый способ сборки —
|
||
CMake; проекты Visual Studio можно собирать по отдельности.
|
||
|
||
## Требования
|
||
|
||
- Windows x64;
|
||
- компилятор с поддержкой C++17;
|
||
- Visual Studio 18 / 2026 с workload для C++ desktop development;
|
||
- CUDA Toolkit 13.3 с интеграцией в Visual Studio для GPU-поиска;
|
||
- NVIDIA GPU с поддерживаемой архитектурой. Сборка содержит цели для Ada `sm_89`
|
||
и Blackwell `sm_120`;
|
||
- Eigen 3.4.0 уже находится в `external/eigen-3.4.0`.
|
||
|
||
Без CUDA проект собирает диагностический stub. Запуск с `--cuda` в такой сборке
|
||
завершается с понятной ошибкой и не переключается на CPU незаметно.
|
||
|
||
## Сборка через CMake
|
||
|
||
Из корня репозитория:
|
||
|
||
```powershell
|
||
cmake --preset vs2026-x64
|
||
cmake --build --preset vs2026-release
|
||
ctest --test-dir build/vs2026 -C Release --output-on-failure
|
||
```
|
||
|
||
Основные исполняемые файлы появятся в `build/vs2026/Release`:
|
||
|
||
- `neighborly_main.exe` — поиск;
|
||
- `polyhedron_gui.exe` — GUI;
|
||
- `verify_cpp.exe` — проверка OBJ;
|
||
- `training_archive_selftest.exe` — regression/self-test локального ML-архива.
|
||
|
||
Для сборки без CUDA используется отдельный каталог:
|
||
|
||
```powershell
|
||
cmake -S . -B build/cpu -G "Visual Studio 18 2026" -A x64 -DSZILASSI_ENABLE_CUDA=OFF
|
||
cmake --build build/cpu --config Release
|
||
```
|
||
|
||
## Сборка отдельных проектов Visual Studio
|
||
|
||
Если CMake не используется, каждый `.vcxproj` собирается отдельно:
|
||
|
||
```powershell
|
||
msbuild projects\Szilassi\Szilassi.vcxproj /m /p:Configuration=Release /p:Platform=x64
|
||
msbuild projects\PolyhedronGui\PolyhedronGui.vcxproj /m /p:Configuration=Release /p:Platform=x64
|
||
msbuild projects\VerifyCpp\VerifyCpp.vcxproj /m /p:Configuration=Release /p:Platform=x64
|
||
msbuild tests\TrainingArchiveSelfTest\TrainingArchiveSelfTest.vcxproj /m /p:Configuration=Release /p:Platform=x64
|
||
```
|
||
|
||
Вывод этих проектов находится в `build/msbuild/bin/x64/Release`.
|
||
|
||
## Штатный запуск через GUI
|
||
|
||
Запустите `polyhedron_gui.exe` из CMake-сборки или `PolyhedronGui.exe` из
|
||
MSBuild-сборки. В интерфейсе остаются две управляющие кнопки:
|
||
|
||
- `Запустить поиск` — продолжает исследование с учётом найденных checkpoint;
|
||
- `Остановить поиск` — ждёт окончания короткого CUDA-пакета и сохраняет изменённое
|
||
состояние перед завершением процесса.
|
||
|
||
Настройки GUI:
|
||
|
||
- количество GPU-цепочек (`0` — автоматический выбор по GPU и occupancy);
|
||
- число итераций в одном коротком CUDA-пакете;
|
||
- длительность запуска;
|
||
- включительный диапазон топологий `0..58`;
|
||
- период durable checkpoint;
|
||
- обычный режим или приоритет проработки худших топологий.
|
||
|
||
GUI автоматически создаёт seed нового процесса. Seed и параметры сохраняются в
|
||
`run.tsv`, поэтому запуск можно воспроизвести без поля Seed в интерфейсе.
|
||
|
||
## Запуск через CLI
|
||
|
||
Пример CUDA-поиска топологий 20–29 в течение восьми часов:
|
||
|
||
```powershell
|
||
.\build\vs2026\Release\neighborly_main.exe --global-search --cuda `
|
||
--topology-from 20 --topology-to 29 --minutes 480 `
|
||
--cuda-chains 0 --cuda-iters 64 --checkpoint-seconds 30 `
|
||
--seed 30000157
|
||
```
|
||
|
||
По умолчанию геометрическое состояние находится в `results/search`. Другой каталог
|
||
задаётся через `--global-dir`. Повторный запуск с тем же каталогом продолжает поиск.
|
||
|
||
Дополнительные режимы можно посмотреть через `--help`:
|
||
|
||
- `--study <obj>` — продолжение оптимизации существующего OBJ;
|
||
- `--repair-local <obj>` — локальная координатная коррекция;
|
||
- `--hunt-local <obj>` — сфокусированный поиск около известных дефектов;
|
||
- `--batch-hunt <obj>` — серия независимых локальных запусков;
|
||
- запуск без режима — интерактивный legacy solver.
|
||
|
||
Проверка модели:
|
||
|
||
```powershell
|
||
.\build\vs2026\Release\verify_cpp.exe --obj path\candidate.obj `
|
||
--topology 42 --eps 1e-13 --report runtime\verify.md
|
||
```
|
||
|
||
## Геометрическое состояние и восстановление
|
||
|
||
Состояние штатного поиска хранится в `results/search`:
|
||
|
||
- `topology_N/resume.planes`, `resume.obj`, `resume.meta` — удобное текущее
|
||
представление лучшего результата;
|
||
- `runs/<UUID>/topology_N/checkpoints/*.szcp` — immutable поколения checkpoint с CRC;
|
||
- `runs/<UUID>/topology_N/archive/*.szar` — MAP-Elites delta-файлы;
|
||
- `runs/<UUID>/run.tsv` и `metrics.tsv` — seed, конфигурация и телеметрия запуска.
|
||
|
||
Новые поколения публикуются атомарно после flush. Повреждённое последнее поколение
|
||
не уничтожает предыдущее валидное. При штатной остановке сохраняются все изменённые
|
||
топологии, а ошибка durable-записи приводит к безопасному завершению с ошибкой.
|
||
|
||
`leaderboard.tsv`, временные файлы и логи являются производными и игнорируются Git;
|
||
leaderboard восстанавливается при следующем запуске.
|
||
|
||
## Локальный ML-датасет
|
||
|
||
Обучающие данные и производные neural-модели являются локальным кэшем и **не входят
|
||
в Git**:
|
||
|
||
- `results/search/runs/<UUID>/training` — `.sztd` shards и активный WAL;
|
||
- `results/search/topology_N/neural` — online-модель `.szonn` и служебные receipts;
|
||
- временные варианты этих файлов и marker достижения лимита.
|
||
|
||
`.gitignore` исключает каталоги `training`, `neural`, все `.sztd/.szonn` и их
|
||
временные варианты. Не используйте `git add -f` для этих путей.
|
||
|
||
Schema v3 сохраняет пригодные для последующего обучения факты: каждый успешный и
|
||
неуспешный CPU-верифицированный кандидат, FP32 chain-best выборку с точным `K/N`,
|
||
CUDA lineage и полный RNG snapshot, начальные и injected предложения, проверенные
|
||
rollout, SPSA double-траектории и старый replay в lossless-виде.
|
||
|
||
WAL имеет CRC и durable commit boundary. После сбоя питания незавершённый хвост
|
||
отбрасывается, а подтверждённые записи сохраняются. Завершённые shards immutable.
|
||
|
||
Общий локальный лимит ML-кэша равен ровно `200000000000` байт (200 GB, не GiB).
|
||
В расчёт входят существующие neural-файлы, резерв 59 финальных моделей и временный
|
||
файл атомарной замены. При достижении лимита:
|
||
|
||
- новые обучающие записи больше не создаются;
|
||
- online-обучение замораживается;
|
||
- геометрический поиск, CPU/DD-проверка и checkpoint продолжаются;
|
||
- программа выводит предупреждение о необходимости пересмотреть формат/политику
|
||
хранения перед дальнейшим накоплением.
|
||
|
||
Лимит рассчитан для одного поискового процесса в одном checkout.
|
||
|
||
## Работа на нескольких компьютерах
|
||
|
||
Для параллельного исследования задавайте непересекающиеся диапазоны топологий.
|
||
Каждый запуск создаёт отдельный UUID, поэтому `.szcp`, `.szar`, манифесты и метрики
|
||
объединяются обычным Git merge без отдельного merge-скрипта.
|
||
|
||
Через Git переносятся только геометрическое состояние и небольшая телеметрия.
|
||
Локальный ML-датасет и neural-модели между компьютерами автоматически не
|
||
объединяются. Не добавляйте весь `results/search` принудительно; проверяйте
|
||
`git status` перед коммитом.
|
||
|
||
## Если локальный ML-кэш уже отслеживается Git
|
||
|
||
Следующая команда удаляет только записи из индекса и сохраняет сами файлы на диске:
|
||
|
||
```powershell
|
||
git rm -r --cached --ignore-unmatch -- `
|
||
":(glob)results/search/**/training/**" `
|
||
":(glob)results/search/**/neural/**" `
|
||
":(glob)results/search/**/*.sztd" `
|
||
":(glob)results/search/**/*.sztd.*" `
|
||
":(glob)results/search/**/*.szonn" `
|
||
":(glob)results/search/**/*.szonn.*" `
|
||
":(glob)results/search/**/TRAINING_DATA_LIMIT_REACHED_REWRITE_REQUIRED.tsv"
|
||
```
|
||
|
||
После этого проверьте результат:
|
||
|
||
```powershell
|
||
git status --short
|
||
git ls-files -ci --exclude-standard -- results/search
|
||
```
|
||
|
||
Затем изменения `.gitignore` и удаление из индекса можно закоммитить и отправить
|
||
обычным способом. `git rm --cached` не очищает старые commits. Если большие файлы
|
||
уже были опубликованы и должны исчезнуть из истории сервера, требуется отдельное
|
||
согласованное переписывание истории (`git filter-repo` и force-push); после него
|
||
остальные клоны необходимо пересоздать или синхронизировать вручную.
|
||
|
||
## Тесты
|
||
|
||
`TrainingArchiveSelfTest` проверяет byte-exact round-trip schema v3, CRC, corruption
|
||
detection, частичные WAL, recovery после сбоя, immutable publication и точную границу
|
||
200 GB.
|
||
|
||
Запуск через CTest:
|
||
|
||
```powershell
|
||
ctest --test-dir build/vs2026 -C Release --output-on-failure
|
||
```
|
||
|
||
Для проверки отдельного OBJ используется `verify_cpp.exe`.
|
||
|
||
## Лицензия
|
||
|
||
Условия использования находятся в [LICENSE](LICENSE).
|