Documentation patch: AppendChangedIndices

[stockfish] / src / nnue / features / half_kp.cpp

diff --git a/src/nnue/features/half_kp.cpp b/src/nnue/features/half_kp.cpp
index 116157cc19d1b6e555fb39a39dd18ee1822fd9a3..8e6907ae00291d07a5dfb643a5764f85065b9d09 100644 (file)
--- a/src/nnue/features/half_kp.cpp
+++ b/src/nnue/features/half_kp.cpp
@@ -1,6 +1,6 @@
 /*
   Stockfish, a UCI chess playing engine derived from Glaurung 2.1
-  Copyright (C) 2004-2020 The Stockfish developers (see AUTHORS file)
+  Copyright (C) 2004-2021 The Stockfish developers (see AUTHORS file)
 
   Stockfish is free software: you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
@@ -21,19 +21,16 @@
 #include "half_kp.h"
 #include "index_list.h"
 
-namespace Eval::NNUE::Features {
+namespace Stockfish::Eval::NNUE::Features {
 
   // Orient a square according to perspective (rotates by 180 for black)
   inline Square orient(Color perspective, Square s) {
     return Square(int(s) ^ (bool(perspective) * 63));
   }
 
-  // Find the index of the feature quantity from the king position and PieceSquare
-  template <Side AssociatedKing>
-  inline IndexType HalfKP<AssociatedKing>::MakeIndex(
-      Color perspective, Square s, Piece pc, Square ksq) {
-
-    return IndexType(orient(perspective, s) + kpp_board_index[pc][perspective] + PS_END * ksq);
+  // Index of a feature for a given king position and another piece on some square
+  inline IndexType make_index(Color perspective, Square s, Piece pc, Square ksq) {
+    return IndexType(orient(perspective, s) + kpp_board_index[perspective][pc] + PS_END * ksq);
   }
 
   // Get a list of indices for active features
@@ -43,13 +40,32 @@ namespace Eval::NNUE::Features {
 
     Square ksq = orient(perspective, pos.square<KING>(perspective));
     Bitboard bb = pos.pieces() & ~pos.pieces(KING);
-    while (bb) {
-      Square s = pop_lsb(&bb);
-      active->push_back(MakeIndex(perspective, s, pos.piece_on(s), ksq));
+    while (bb)
+    {
+      Square s = pop_lsb(bb);
+      active->push_back(make_index(perspective, s, pos.piece_on(s), ksq));
     }
   }
 
-  // Get a list of indices for recently changed features
+
+  // AppendChangedIndices() : get a list of indices for recently changed features
+
+  // IMPORTANT: The `pos` in this function is pretty much useless as it
+  // is not always the position the features are updated to. The feature
+  // transformer code right now can update multiple accumulators per move,
+  // but since Stockfish only keeps the full state of the current leaf
+  // search position it is not possible to always pass here the position for
+  // which the accumulator is being updated. Therefore the only thing that
+  // can be reliably extracted from `pos` is the king square for the king
+  // of the `perspective` color (note: not even the other king's square will
+  // match reality in all cases, this is also the reason why `dp` is passed
+  // as a parameter and not extracted from pos.state()). This is of particular
+  // problem for future nets with other feature sets, where updating the active
+  // feature might require more information from the intermediate positions. In
+  // this case the only easy solution is to remove the multiple updates from
+  // the feature transformer update code and only update the accumulator for
+  // the current leaf position (the position after the move).
+
   template <Side AssociatedKing>
   void HalfKP<AssociatedKing>::AppendChangedIndices(
       const Position& pos, const DirtyPiece& dp, Color perspective,
@@ -60,12 +76,12 @@ namespace Eval::NNUE::Features {
       Piece pc = dp.piece[i];
       if (type_of(pc) == KING) continue;
       if (dp.from[i] != SQ_NONE)
-        removed->push_back(MakeIndex(perspective, dp.from[i], pc, ksq));
+        removed->push_back(make_index(perspective, dp.from[i], pc, ksq));
       if (dp.to[i] != SQ_NONE)
-        added->push_back(MakeIndex(perspective, dp.to[i], pc, ksq));
+        added->push_back(make_index(perspective, dp.to[i], pc, ksq));
     }
   }
 
   template class HalfKP<Side::kFriend>;
 
-}  // namespace Eval::NNUE::Features
+}  // namespace Stockfish::Eval::NNUE::Features