Search improvements

README.md

@@ -32,18 +32,31 @@ 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
+it combines saved archive seeds with independent random starts. A UCB-style bandit assigns
+the 30/16/8 depth budgets using recent improvement, solution quality, uncertainty, and
+staleness; every fifth cycle still refreshes the whole selected range, so no topology can
+be starved indefinitely. A clean stop saves each
 topology under `results\search\topology_N`; pressing the same button later resumes only
 those checkpoints. `results\search\leaderboard.tsv` is the current ranking.
 
 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
+stagnation, and restart state between batches. Twenty-five percent of chains remain the
+unchanged simulated-annealing control; disjoint cohorts add replica exchange, adaptive
+move selection, population-based exploit/mutate, and MAP-Elites/CEM seed injection.
+Strategy quotas and one descendant per injected seed reach CPU verification even when
+they are outside the global GPU top-N. A small SPSA+Adam refinement runs in CPU double,
+but its output is rounded back to exact FP32 and rechecked before it can be accepted.
+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`.
 
+The MAP-Elites archive separates geometry into determinant, edge-ratio, turn-angle, and
+extent bins. All valid historical checkpoint generations are deduplicated and re-evaluated
+on startup, so accumulated searches seed the archive instead of merely supplying one best
+shape per topology. Diagonal CEM is updated only from new injected descendants, avoiding
+repeatedly learning from the same persistent chain best.
+
 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
@@ -56,11 +69,26 @@ Each checkpoint is an immutable, self-contained `.szcp` file with CRC-32 and exa
 bit patterns. It is flushed to disk and atomically published; a damaged newest generation
 is ignored in favor of the previous valid one.
 
+Archive improvements use immutable `.szar` delta files in the same run UUID namespace.
+Each delta contains only cells opened or improved since the preceding durable write; CRC,
+atomic publication, and deterministic per-cell selection make a normal Git merge a union
+of useful results. Serialized energies are never trusted across run settings: every distinct
+state is re-evaluated under the current objective before cells are compared.
+
+The checkpoint timer sweeps every changed topology, not just the topology currently chosen
+by the bandit. Thus an improvement cannot remain only in memory because that topology is
+not scheduled again. On clean stop all outstanding `.szcp` and `.szar` generations are
+flushed; if durable writing fails, the stop marker is retained and the process returns an
+error instead of reporting a successful stop.
+
 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.
+Each UUID run also has a tracked `metrics.tsv` with per-strategy accounted search work, archive,
+replica-exchange, SPSA, and scheduler telemetry; independent computers create different
+paths, so these files merge without a custom script.
 
 ## Project layout
 
@@ -68,6 +96,7 @@ rescans checkpoints, repeats CPU/DD validation, and rebuilds the leaderboard.
 * `projects/VerifyCpp` — the high-precision verifier.
 * `projects/PolyhedronGui` — the Windows launcher.
 * `src/NeighborlyCore` — shared geometry and utility code.
+* `src/SearchArchive` — durable Git-mergeable MAP-Elites delta storage.
 * `data` — topology definitions and input models.
 * `results/topologies` and `results/showcases` — saved research models.
 * `results/search` — Git-mergeable search states and durable checkpoint generations.