CUDA

README.md

@@ -9,17 +9,58 @@ The conclusion is: Sort of. I believe there isn't a shape that is _completely_ i
 
 Build `Szilassi.slnx` as `Release|x64`, then open
 `build\msbuild\bin\x64\Release\PolyhedronGui.exe`.
-For an independent overnight run, leave `Threads` at `0`, set the desired number of
-minutes, and click **Глобальный поиск 59**. This mode does not use the supplied near-miss:
+The GUI intentionally has only **Запустить поиск** and **Остановить поиск** buttons.
+Select an inclusive topology range, then start the search. Existing checkpoints are
+loaded automatically. Stop waits for the current short CUDA kernel, synchronizes the
+device, writes a durable checkpoint, and only then exits.
+
+The GUI creates a fresh seed automatically for every new process. It is shown in the
+GUI log and saved in the durable, Git-tracked `runs/<UUID>/run.tsv` manifest together
+with the topology range and search parameters, so a run can be reproduced without
+typing a seed into the interface.
+
+The search process and CUDA stream run at low scheduling priority, so foreground work
+keeps priority. There is no artificial duty-cycle throttle. Kernels remain short for
+responsive stopping and Windows WDDM stability.
+
+Leave `GPU chains` at `0` for automatic sizing. The CUDA backend derives the chain count
+from the selected GPU's SM count and measured kernel occupancy, so Ada `sm_89` and
+Blackwell `sm_120` use different appropriate values. Each selected topology keeps its
+annealing session resident on the device, so refresh cycles cannot discard cooling,
+stagnation, or restart state. The full 59-topology range uses about 1.4 GB of VRAM on
+the 12 GB RTX 4070 Ti; narrower ranges allocate proportionally less.
+
+For an independent overnight run, set the desired number of minutes and topology range.
+This mode does not use the supplied near-miss:
 it gives every topology fresh random starts, then alternates depth passes over the best
 30/16/8 topologies with periodic breadth refreshes over all 59. A clean stop saves each
-topology under `runtime\global_search\topology_N`; pressing the same button later resumes only
-those checkpoints. `runtime\global_search\leaderboard.tsv` is the current ranking.
+topology under `results\search\topology_N`; pressing the same button later resumes only
+those checkpoints. `results\search\leaderboard.tsv` is the current ranking.
 
-Coordinates and optimizer states use 64-bit `double`. Candidates with at most 12 total
-defects are automatically reclassified with the custom `WideReal` double-double type
-(about 31 decimal digits), and every claimed `0/0` is serialized and checked again at
-multiple tolerances down to `1e-13`. OBJ and plane checkpoints retain 17 digits.
+The CUDA hot path uses standard FP32 math. Persistent chains retain their RNG, cooling,
+stagnation, and restart state between batches; fixed fresh cohorts preserve global
+exploration during breadth/refresh passes. Every returned shortlist is reconstructed and checked on
+the CPU in `double`; candidates with at most 12 total defects are reclassified with the
+custom `WideReal` double-double type (about 31 decimal digits). Every claimed `0/0` is
+serialized and checked again at multiple tolerances down to `1e-13`.
+
+CUDA Toolkit 13.3 with Visual Studio integration is required for the GPU backend. The
+build contains native targets for Ada `sm_89` and Blackwell `sm_120`. Without the Toolkit,
+the project builds a diagnostic stub and refuses `--cuda` instead of silently falling
+back to the CPU.
+
+### Checkpoints and Git
+
+Search state is stored in `results/search`, which is intentionally tracked by Git.
+Each checkpoint is an immutable, self-contained `.szcp` file with CRC-32 and exact FP32
+bit patterns. It is flushed to disk and atomically published; a damaged newest generation
+is ignored in favor of the previous valid one.
+
+For several computers, assign non-overlapping topology ranges. Each process uses a unique
+run UUID, so checkpoint filenames do not collide. Commit `results/search` normally on each
+computer and merge the branches with Git. `leaderboard.tsv`, run logs, and temporary files
+are derived and ignored, so they cannot create merge conflicts; the next search start
+rescans checkpoints, repeats CPU/DD validation, and rebuilds the leaderboard.
 
 ## Project layout
 
@@ -29,7 +70,8 @@ multiple tolerances down to `1e-13`. OBJ and plane checkpoints retain 17 digits.
 * `src/NeighborlyCore` — shared geometry and utility code.
 * `data` — topology definitions and input models.
 * `results/topologies` and `results/showcases` — saved research models.
-* `runtime` — generated candidates, reports, logs, and resumable search state.
+* `results/search` — Git-mergeable search states and durable checkpoint generations.
+* `runtime` — temporary stop files, reports, logs, and local candidates.
 * `scripts` — helper launch and reporting scripts.
 
 All Visual Studio projects are collected by the root `Szilassi.slnx`. MSBuild output is
@@ -39,7 +81,8 @@ centralized under `build/msbuild`; CMake output remains under `build/vs2026`.
 To start a search, build and run the `Szilassi` project.
 
 ### Requirements
-* C++17 compatible compiler (I'm using MSVC 2019).
+* C++17 compatible compiler (Visual Studio 2026 is configured by the current presets).
+* [CUDA Toolkit 13.3](https://developer.nvidia.com/cuda-downloads) with Visual Studio integration for GPU search.
 * [Eigen-3.4.0](https://eigen.tuxfamily.org/) though similar versions should work as well.
 * [Cairo-1.17.2](https://www.cairographics.org/) (optional) this is only needed to render paper cutouts.