Skip to content

Commit eb8bd18

Browse files
committed
Cache exact static evaluations privately per search worker
1 parent 836b1e0 commit eb8bd18

72 files changed

Lines changed: 1176 additions & 21 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CMakeLists.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,3 +92,12 @@ if(CAISSA_NETWORK_WIDTH STREQUAL "64")
9292
else()
9393
add_test(NAME neural_bounds COMMAND neural_bounds_test)
9494
endif()
95+
96+
add_executable(evaluation_cache_test tests/evaluation_cache_test.cpp)
97+
target_link_libraries(evaluation_cache_test PRIVATE caissa_core)
98+
if(CAISSA_NETWORK_WIDTH STREQUAL "64")
99+
add_test(NAME evaluation_cache COMMAND evaluation_cache_test ${CMAKE_SOURCE_DIR}/models/residual-prefix-diagnostic.cai ${CMAKE_SOURCE_DIR}/models/diagnostic-v2.cai)
100+
else()
101+
add_test(NAME evaluation_cache COMMAND evaluation_cache_test)
102+
endif()
103+
set_tests_properties(evaluation_cache PROPERTIES TIMEOUT 180)

‎docs/notes/evaluation-cache.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Exact static evaluation cache
2+
3+
Each search worker can own a 32768-entry direct-mapped cache for exact static evaluations. A valid bit distinguishes an empty entry from key or score zero. Lookup compares the entire 64-bit board key, and a different key at the same index replaces the old entry. The hash collision assumption matches the existing transposition table. At the current ABI the storage is 512 KiB per enabled worker, at most 4 MiB across eight workers. This is additional to the configured transposition-table memory and is reported separately.
4+
5+
The value is the underlying evaluator's exact score, before draw-claim handling, search windows or mate-distance decisions. Classical contract 1 and the neural feature model depend on board placement and mover, so earlier history and rule clocks do not alter that raw score. Search still evaluates legal termination and draw history before considering static evaluation. A worker's network, neural percentage and scalar/native choice are immutable for its lifetime. Workers are rebuilt for each search, preventing reuse across model or option changes. No cache state is shared across threads.
6+
7+
Only a complete evaluation can enter the cache. A certified stand-pat lower bound is deliberately not stored. A previously cached exact score remains usable at another threshold. The cache does not store a claim score, quiescence result, TT bound or mate score. The unchanged classical evaluator remains the comparison control.
8+
9+
`Evaluation Cache` is an off-by-default UCI option. `evaluation_cache_hits` and `evaluation_cache_bytes` appear in search statistics. `eval_calls` counts evaluation requests, including cache hits; `neural_evaluations` counts actual complete network inferences. Timing includes the lookup. Disabling the option allocates no cache.
10+
11+
The native test covers key/score zero, forced index collisions, rejection of mate/bound sentinels, standard and Chess960 positions, actual repetition history, neural and classical evaluators, scalar mode, fixed-node PV/score/tree-counter equality, private multi-thread memory and certified-bound interactions. It passed 120 paired native cases with 625195 requests and 236432 hits. All 14 release native tests passed. The sanitizer run passed the prior 13 cases, then its final cache case was terminated at the real wall deadline during a large wall/active-time gap. The 1800-second development budget remains exhausted. This is incomplete sanitizer evidence, so the feature stays disabled and cannot claim full systems acceptance.
12+
13+
A separate fixed-node cost experiment retained 144 actual searches over eight positions, three repeats and classical/ten-percent/full-neural modes. Every cached/uncached pair preserved its outputs and search-tree counters. Twelve observations exhausted the node budget before completing a depth and returned actual legal fallback moves; they have no invented PV or score. The independent checker reran every query through the saved executable, reconstructed legal PVs, request timing, counters, aggregates and ratios without importing producer transport or parsing code.
14+
15+
In the ten-percent mode, actual network inferences fell from 337569 to 159489. Median cached/uncached roundtrip ratio was 0.829; the classical ratio was 0.949 and the full-neural ratio 0.890. The corpus verifier was active during this small cost run. Timing is descriptive under that load; it is not an Elo measurement or evidence of isolation. A position's measured timing ratio reached 1.623, so the median does not describe every position.
16+
17+
Failures remain visible. The initial native fixture failed to compile because its initializer mixed `string_view` and string literals. Independent replay first exposed a redundant forced-signal cleanup race; graceful protocol teardown corrected it. It then rejected a real zero-completed-depth fallback under an overly strict PV requirement. The checker now accepts only a legal fallback with actual zero completed-depth nodes. An initial textual fix left the old requirement in place and its failed replay is also retained. All successful cost replay work remained inside its original 900-second scope. Additional proposed parser controls did not run because that scope had expired, and are recorded as not executed.
18+
19+
[Raw native, sanitizer, cost and independent replay records](../../results/evaluation-cache-2026-10-24/) preserve the actual failures and identities. `verification/native_session.py` owns finite nonblocking native pipes and cleanup; `verification/evaluation_cost.py` interprets the frozen observations and checks the saved engine independently. The current metadata/observation ceilings are 1 MiB/128 MiB. Further full-source sanitizer, strength and systems measurements remain required.
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
#pragma once
2+
#include "caissa/types.hpp"
3+
#include <array>
4+
#include <optional>
5+
6+
namespace caissa {
7+
// Exact static evaluations only. Each search worker owns its own cache, so its
8+
// network, deployment percentage and evaluation contract cannot change lifetime.
9+
// Board hash collisions have the same full 64-bit identity assumption as the TT.
10+
class EvaluationCache {
11+
public:
12+
static constexpr std::size_t capacity=32768;
13+
std::optional<int> find(Key key) const noexcept {
14+
const auto& entry=entries_[static_cast<std::size_t>(key)&(capacity-1)];
15+
if(entry.valid&&entry.key==key)return entry.score;
16+
return std::nullopt;
17+
}
18+
void store(Key key,int score) {
19+
if(score<=-mate_threshold||score>=mate_threshold)
20+
throw InputError("evaluation cache requires an exact non-mate static score");
21+
entries_[static_cast<std::size_t>(key)&(capacity-1)]={key,score,true};
22+
}
23+
std::size_t bytes() const noexcept {return sizeof(entries_);}
24+
private:
25+
struct Entry {Key key=0;int score=0;bool valid=false;};
26+
std::array<Entry,capacity> entries_{};
27+
};
28+
}

‎include/caissa/search.hpp‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ namespace caissa {
1010
struct SearchOptions {
1111
bool table=true, pvs=true, aspiration=true, quiescence=true;
1212
bool null_move=true, lmr=true, extensions=true, history=true, see=true;
13-
bool futility=true, ordering_hints=false, neural_bounds=false;
13+
bool futility=true, ordering_hints=false, neural_bounds=false, evaluation_cache=false;
1414
int threads=1, multipv=1,trace_limit=0;
1515
int inject_worker_start_failure_after=-1;
1616
std::shared_ptr<const Network> network;
@@ -42,6 +42,7 @@ struct SearchStats {
4242
std::uint64_t null_cutoffs=0,lmr_searches=0,researches=0,futility_skips=0;
4343
std::uint64_t evaluator_calls=0,evaluator_ns=0,ordering_hint_hits=0;
4444
std::uint64_t neural_evaluations=0,neural_bound_cutoffs=0;
45+
std::uint64_t evaluation_cache_hits=0,evaluation_cache_bytes=0;
4546
int seldepth=0;
4647
SearchStats& operator+=(const SearchStats& rhs);
4748
};

0 commit comments

Comments
 (0)