2 Stockfish, a UCI chess playing engine derived from Glaurung 2.1
3 Copyright (C) 2004-2023 The Stockfish developers (see AUTHORS file)
5 Stockfish is free software: you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
10 Stockfish is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
19 // Code for calculating NNUE evaluation function
21 #include "evaluate_nnue.h"
30 #include <string_view>
32 #include "../evaluate.h"
34 #include "../position.h"
37 #include "nnue_accumulator.h"
38 #include "nnue_common.h"
40 namespace Stockfish::Eval::NNUE {
42 // Input feature converter
43 LargePagePtr<FeatureTransformer> featureTransformer;
45 // Evaluation function
46 AlignedPtr<Network> network[LayerStacks];
48 // Evaluation function file name
50 std::string netDescription;
54 // Initialize the evaluation function parameters
56 void initialize(AlignedPtr<T>& pointer) {
58 pointer.reset(reinterpret_cast<T*>(std_aligned_alloc(alignof(T), sizeof(T))));
59 std::memset(pointer.get(), 0, sizeof(T));
63 void initialize(LargePagePtr<T>& pointer) {
65 static_assert(alignof(T) <= 4096,
66 "aligned_large_pages_alloc() may fail for such a big alignment requirement of T");
67 pointer.reset(reinterpret_cast<T*>(aligned_large_pages_alloc(sizeof(T))));
68 std::memset(pointer.get(), 0, sizeof(T));
71 // Read evaluation function parameters
73 bool read_parameters(std::istream& stream, T& reference) {
76 header = read_little_endian<std::uint32_t>(stream);
77 if (!stream || header != T::get_hash_value())
79 return reference.read_parameters(stream);
82 // Write evaluation function parameters
84 bool write_parameters(std::ostream& stream, const T& reference) {
86 write_little_endian<std::uint32_t>(stream, T::get_hash_value());
87 return reference.write_parameters(stream);
93 // Initialize the evaluation function parameters
94 static void initialize() {
96 Detail::initialize(featureTransformer);
97 for (std::size_t i = 0; i < LayerStacks; ++i)
98 Detail::initialize(network[i]);
101 // Read network header
102 static bool read_header(std::istream& stream, std::uint32_t* hashValue, std::string* desc) {
103 std::uint32_t version, size;
105 version = read_little_endian<std::uint32_t>(stream);
106 *hashValue = read_little_endian<std::uint32_t>(stream);
107 size = read_little_endian<std::uint32_t>(stream);
108 if (!stream || version != Version)
111 stream.read(&(*desc)[0], size);
112 return !stream.fail();
115 // Write network header
116 static bool write_header(std::ostream& stream, std::uint32_t hashValue, const std::string& desc) {
117 write_little_endian<std::uint32_t>(stream, Version);
118 write_little_endian<std::uint32_t>(stream, hashValue);
119 write_little_endian<std::uint32_t>(stream, std::uint32_t(desc.size()));
120 stream.write(&desc[0], desc.size());
121 return !stream.fail();
124 // Read network parameters
125 static bool read_parameters(std::istream& stream) {
127 std::uint32_t hashValue;
128 if (!read_header(stream, &hashValue, &netDescription))
130 if (hashValue != HashValue)
132 if (!Detail::read_parameters(stream, *featureTransformer))
134 for (std::size_t i = 0; i < LayerStacks; ++i)
135 if (!Detail::read_parameters(stream, *(network[i])))
137 return stream && stream.peek() == std::ios::traits_type::eof();
140 // Write network parameters
141 static bool write_parameters(std::ostream& stream) {
143 if (!write_header(stream, HashValue, netDescription))
145 if (!Detail::write_parameters(stream, *featureTransformer))
147 for (std::size_t i = 0; i < LayerStacks; ++i)
148 if (!Detail::write_parameters(stream, *(network[i])))
153 void hint_common_parent_position(const Position& pos) {
154 featureTransformer->hint_common_access(pos);
157 // Evaluation function. Perform differential calculation.
158 Value evaluate(const Position& pos, bool adjusted, int* complexity) {
160 // We manually align the arrays on the stack because with gcc < 9.3
161 // overaligning stack variables with alignas() doesn't work correctly.
163 constexpr uint64_t alignment = CacheLineSize;
164 constexpr int delta = 24;
166 #if defined(ALIGNAS_ON_STACK_VARIABLES_BROKEN)
167 TransformedFeatureType
168 transformedFeaturesUnaligned[FeatureTransformer::BufferSize
169 + alignment / sizeof(TransformedFeatureType)];
171 auto* transformedFeatures = align_ptr_up<alignment>(&transformedFeaturesUnaligned[0]);
173 alignas(alignment) TransformedFeatureType transformedFeatures[FeatureTransformer::BufferSize];
176 ASSERT_ALIGNED(transformedFeatures, alignment);
178 const int bucket = (pos.count<ALL_PIECES>() - 1) / 4;
179 const auto psqt = featureTransformer->transform(pos, transformedFeatures, bucket);
180 const auto positional = network[bucket]->propagate(transformedFeatures);
183 *complexity = abs(psqt - positional) / OutputScale;
185 // Give more value to positional evaluation when adjusted flag is set
187 return static_cast<Value>(((1024 - delta) * psqt + (1024 + delta) * positional)
188 / (1024 * OutputScale));
190 return static_cast<Value>((psqt + positional) / OutputScale);
193 struct NnueEvalTrace {
194 static_assert(LayerStacks == PSQTBuckets);
196 Value psqt[LayerStacks];
197 Value positional[LayerStacks];
198 std::size_t correctBucket;
201 static NnueEvalTrace trace_evaluate(const Position& pos) {
203 // We manually align the arrays on the stack because with gcc < 9.3
204 // overaligning stack variables with alignas() doesn't work correctly.
205 constexpr uint64_t alignment = CacheLineSize;
207 #if defined(ALIGNAS_ON_STACK_VARIABLES_BROKEN)
208 TransformedFeatureType
209 transformedFeaturesUnaligned[FeatureTransformer::BufferSize
210 + alignment / sizeof(TransformedFeatureType)];
212 auto* transformedFeatures = align_ptr_up<alignment>(&transformedFeaturesUnaligned[0]);
214 alignas(alignment) TransformedFeatureType transformedFeatures[FeatureTransformer::BufferSize];
217 ASSERT_ALIGNED(transformedFeatures, alignment);
220 t.correctBucket = (pos.count<ALL_PIECES>() - 1) / 4;
221 for (IndexType bucket = 0; bucket < LayerStacks; ++bucket)
223 const auto materialist = featureTransformer->transform(pos, transformedFeatures, bucket);
224 const auto positional = network[bucket]->propagate(transformedFeatures);
226 t.psqt[bucket] = static_cast<Value>(materialist / OutputScale);
227 t.positional[bucket] = static_cast<Value>(positional / OutputScale);
233 constexpr std::string_view PieceToChar(" PNBRQK pnbrqk");
236 // Converts a Value into (centi)pawns and writes it in a buffer.
237 // The buffer must have capacity for at least 5 chars.
238 static void format_cp_compact(Value v, char* buffer) {
240 buffer[0] = (v < 0 ? '-' : v > 0 ? '+' : ' ');
242 int cp = std::abs(UCI::to_cp(v));
245 buffer[1] = '0' + cp / 10000;
247 buffer[2] = '0' + cp / 1000;
249 buffer[3] = '0' + cp / 100;
254 buffer[1] = '0' + cp / 1000;
256 buffer[2] = '0' + cp / 100;
259 buffer[4] = '0' + cp / 10;
263 buffer[1] = '0' + cp / 100;
266 buffer[3] = '0' + cp / 10;
268 buffer[4] = '0' + cp / 1;
273 // Converts a Value into pawns, always keeping two decimals
274 static void format_cp_aligned_dot(Value v, std::stringstream& stream) {
276 const double pawns = std::abs(0.01 * UCI::to_cp(v));
278 stream << (v < 0 ? '-'
281 << std::setiosflags(std::ios::fixed) << std::setw(6) << std::setprecision(2) << pawns;
285 // Returns a string with the value of each piece on a board,
286 // and a table for (PSQT, Layers) values bucket by bucket.
287 std::string trace(Position& pos) {
289 std::stringstream ss;
291 char board[3 * 8 + 1][8 * 8 + 2];
292 std::memset(board, ' ', sizeof(board));
293 for (int row = 0; row < 3 * 8 + 1; ++row)
294 board[row][8 * 8 + 1] = '\0';
296 // A lambda to output one box of the board
297 auto writeSquare = [&board](File file, Rank rank, Piece pc, Value value) {
298 const int x = int(file) * 8;
299 const int y = (7 - int(rank)) * 3;
300 for (int i = 1; i < 8; ++i)
301 board[y][x + i] = board[y + 3][x + i] = '-';
302 for (int i = 1; i < 3; ++i)
303 board[y + i][x] = board[y + i][x + 8] = '|';
304 board[y][x] = board[y][x + 8] = board[y + 3][x + 8] = board[y + 3][x] = '+';
306 board[y + 1][x + 4] = PieceToChar[pc];
307 if (value != VALUE_NONE)
308 format_cp_compact(value, &board[y + 2][x + 2]);
311 // We estimate the value of each piece by doing a differential evaluation from
312 // the current base eval, simulating the removal of the piece from its square.
313 Value base = evaluate(pos);
314 base = pos.side_to_move() == WHITE ? base : -base;
316 for (File f = FILE_A; f <= FILE_H; ++f)
317 for (Rank r = RANK_1; r <= RANK_8; ++r)
319 Square sq = make_square(f, r);
320 Piece pc = pos.piece_on(sq);
321 Value v = VALUE_NONE;
323 if (pc != NO_PIECE && type_of(pc) != KING)
325 auto st = pos.state();
327 pos.remove_piece(sq);
328 st->accumulator.computed[WHITE] = false;
329 st->accumulator.computed[BLACK] = false;
331 Value eval = evaluate(pos);
332 eval = pos.side_to_move() == WHITE ? eval : -eval;
335 pos.put_piece(pc, sq);
336 st->accumulator.computed[WHITE] = false;
337 st->accumulator.computed[BLACK] = false;
340 writeSquare(f, r, pc, v);
343 ss << " NNUE derived piece values:\n";
344 for (int row = 0; row < 3 * 8 + 1; ++row)
345 ss << board[row] << '\n';
348 auto t = trace_evaluate(pos);
350 ss << " NNUE network contributions "
351 << (pos.side_to_move() == WHITE ? "(White to move)" : "(Black to move)") << std::endl
352 << "+------------+------------+------------+------------+\n"
353 << "| Bucket | Material | Positional | Total |\n"
354 << "| | (PSQT) | (Layers) | |\n"
355 << "+------------+------------+------------+------------+\n";
357 for (std::size_t bucket = 0; bucket < LayerStacks; ++bucket)
359 ss << "| " << bucket << " ";
361 format_cp_aligned_dot(t.psqt[bucket], ss);
364 format_cp_aligned_dot(t.positional[bucket], ss);
367 format_cp_aligned_dot(t.psqt[bucket] + t.positional[bucket], ss);
370 if (bucket == t.correctBucket)
371 ss << " <-- this bucket is used";
375 ss << "+------------+------------+------------+------------+\n";
381 // Load eval, from a file stream or a memory stream
382 bool load_eval(std::string name, std::istream& stream) {
386 return read_parameters(stream);
389 // Save eval, to a file stream or a memory stream
390 bool save_eval(std::ostream& stream) {
392 if (fileName.empty())
395 return write_parameters(stream);
398 // Save eval, to a file given by its name
399 bool save_eval(const std::optional<std::string>& filename) {
401 std::string actualFilename;
404 if (filename.has_value())
405 actualFilename = filename.value();
408 if (currentEvalFileName != EvalFileDefaultName)
410 msg = "Failed to export a net. "
411 "A non-embedded net can only be saved if the filename is specified";
413 sync_cout << msg << sync_endl;
416 actualFilename = EvalFileDefaultName;
419 std::ofstream stream(actualFilename, std::ios_base::binary);
420 bool saved = save_eval(stream);
422 msg = saved ? "Network saved successfully to " + actualFilename : "Failed to export a net";
424 sync_cout << msg << sync_endl;
429 } // namespace Stockfish::Eval::NNUE