Position Evaluation and NNUE
Evaluation estimates the current position; search compares what happens when both sides continue. NNUE helps search allocate attention. Search and position code handle mates, repetitions, and historical rules.
This page follows official Pikafish commit 1c66b9b, covering inference inputs, computation, and output. Training-data origins, scale, and training procedures require the corresponding training material.
From Board to Score
An ordinary static evaluation has four stages:
- Encode piece locations and selected attack relationships as feature indices.
- Update accumulators and run later layers to obtain the raw NNUE score.
- Scale it in
evaluate.cppusing material, search-providedoptimism, and the move-limit counter. - Apply search corrections as needed and recursively compare continuations.
Display scores undergo another conversion; see Score Output. Track each stage's origin and purpose separately. Search use is covered in Search and Evaluation.
Sources: network evaluation, evaluation entry, search corrections.
How Does evaluate.cpp Adjust the Network Score?
Eval::evaluate() requires a position out of check. It calls the network, then scale_evaluation(). Checked nodes follow the search's evasion paths. simple_eval() calculates a rough material balance from pawns, advisors, elephants, chariots, horses, and cannons, for comparison with NNUE.
The code normalizes material and NNUE scores into bounded scales and measures their alignment. A position down material but with attacking compensation differs from one ahead in material and also favored by the network. Alignment, raw score, and root-search optimism are combined, then scaled by total board material.
Two final steps damp the ordinary score towards zero as rule60 grows, using v -= v * rule60 / 244, and clamp it to the ordinary evaluation range, reserving a separate range for decisive results. These constants belong to the fixed commit. Rules and search handle actual move-limit or mating terminals.
A number can therefore be traced through raw NNUE, scaled static evaluation, search correction, search return value, and display conversion. Sources: material comparison and scaling, origin of optimism.
NNUE Input Features
| Feature | Information recorded |
|---|---|
HalfKAv2_hm | Piece types and squares, grouped using both king locations, mirroring, and friendly chariot/horse/cannon configuration. |
FullThreats | Selected attack and protection relationships on the current board. |
Position features select a bucket and transform coordinates and colors for the perspective. make_index() turns the transformed piece, square, and bucket into an integer used to look up weights.
Relationship features come from current attacks and occupied squares, with filters for piece combinations and duplicate relationships. They describe present interactions. Establishing a mating sacrifice requires searching continuations; identifying a rule-defined chase requires historical and exchange checks in the rule module.
Red and Black have separate perspectives, ordered with the moving side first for the later layers. The final score is from that side's viewpoint. Sources: position indices and buckets, relationships, two-perspective transformation.
Shared Front End, Material-Selected Later Layers
Each Network contains a feature transformer and 16 sets of later-layer parameters. make_layer_stack_bucket() chooses one from the chariot counts and combined horse/cannon counts on both sides. Equal chariot counts and configurations where only one side has chariots can select different buckets.
The later-layer input has 1024 dimensions; two intermediate affine layers each output 32 values, ending in one score. Actual connections also concatenate clipped and squared activations and include a connection from an earlier layer to the output. Read these connections when examining computation cost, using widths as an overview.
Dimensions are learned computational channels whose weights jointly form the score. Interpreting their chess meaning requires further analysis. Sources: layers and propagation, bucket selection, evaluation entry.
How Are Accumulators Updated Incrementally?
Inputs are sparse: only part of a potentially large feature space is active on a given board. The front end can be summarized as a bias plus the weight columns for active features:
A = bias + sum(W[active_feature])This is an explanatory formula; the implementation maintains position and relationship contributions separately and uses quantized scales.
Suppose a chariot moves from e0 to e1 with bucket and mirroring unchanged. Its position contribution can be updated by subtracting the weights for the chariot on e0 and adding those for e1. Capturing a Black cannon also removes that cannon's contribution. Attack relationships opened or closed by the move have their own additions and removals.
The search stack records changes and finds a reusable state when evaluation is needed, then applies the missing updates. Later layers still run for each evaluation, and undoing a move returns to its state. The transposition table reuses search results; accumulators reuse front-end computation.
A friendly king move, a capture that changes the feature bucket, or changed mirroring requires a refresh for the affected perspective. Caches organized by king location and other information can help: update position contributions from piece differences, then add current relationships. Sources: accumulator stack, delta updates, refresh conditions, refresh caches.
Reducing Cost with Quantization and SIMD
Inference uses integers with defined scales: 8-bit feature weights, 16-bit accumulators, and 32-bit later-layer multiply-add results, combined with clipping, shifts, and scaling. Quantization reduces storage and memory traffic and suits CPU integer-vector instructions.
SIMD processes several channels per instruction, including SSE/AVX on x86 and NEON on ARM. Some layers skip work for zero inputs. Performance depends on CPU, build path, memory access, and the share of search time spent evaluating.
Sources: integer types and scales, feature transformation, multiply-add implementation, sparse input layer.
Loading Networks and Checking Compatibility
EvalFile selects the file, normally pikafish.nnue. The loader tries the applicable paths, reads the format version, architecture identifier, and layer parameters, and checks completeness. Failed verification reports path and compatibility issues and terminates.
A replacement network needs compatible architecture, format, and parameters. The architecture identifier supports format checks; publisher-provided checksums can additionally help verify file origin and integrity.
Sources: default filename, loading paths, format checks, verification.
Reading eval Debug Output
eval shows a static evaluation breakdown. It includes NNUE internal units from the side to move and display scores converted to Red's perspective. The retained white side label refers to Red in this Xiangqi code.
The debug entry uses zero optimism for the final static score, whereas search nodes have their own corrections and continuations. Read eval and go as static and searched scores respectively. In check, the debug entry reports that no ordinary final static evaluation is available.
Sources: eval entry, debug output. See Score Output for cp, mate, and WDL, and Why do AIs often struggle to find mate? for mate-finding in winning positions.
