1use crate::{Color, Move, MoveKind, Piece, PieceKind, Position, Square};
10use std::fmt;
11use std::sync::LazyLock;
12
13pub const FEATURE_COUNT: usize = 2 * 6 * 64;
14pub const HIDDEN: usize = 128;
15pub(crate) const OUTPUT_INPUTS: usize = HIDDEN * 2;
16pub const QA: i32 = 4096;
19pub const QB: i32 = 64;
20
21const MAGIC: [u8; 8] = *b"GAINNUE\0";
22const VERSION: u16 = 1;
23const ACTIVATION_CRELU: u8 = 1;
24const HEADER_BYTES: usize = 32;
25const PAYLOAD_BYTES: usize = HIDDEN * 2 + FEATURE_COUNT * HIDDEN * 2 + OUTPUT_INPUTS * 2 + 4;
26
27static BUILTIN_NETWORK: LazyLock<QuantizedNetwork> = LazyLock::new(|| {
28 QuantizedNetwork::from_bytes(include_bytes!("../networks/tiny-v1.gainnue"))
29 .expect("the embedded tiny NNUE must pass its version and checksum gates")
30});
31
32pub fn builtin_network() -> &'static QuantizedNetwork {
33 &BUILTIN_NETWORK
34}
35
36#[derive(Debug, Clone, PartialEq)]
38pub struct FloatNetwork {
39 feature_bias: Vec<f32>,
40 feature_weights: Vec<f32>,
41 output_weights: Vec<f32>,
42 output_bias: f32,
43}
44
45impl FloatNetwork {
46 pub fn new(
47 feature_bias: Vec<f32>,
48 feature_weights: Vec<f32>,
49 output_weights: Vec<f32>,
50 output_bias: f32,
51 ) -> Result<Self, NetworkError> {
52 if feature_bias.len() != HIDDEN
53 || feature_weights.len() != FEATURE_COUNT * HIDDEN
54 || output_weights.len() != OUTPUT_INPUTS
55 {
56 return Err(NetworkError::Dimensions);
57 }
58 if !output_bias.is_finite()
59 || feature_bias.iter().any(|value| !value.is_finite())
60 || feature_weights.iter().any(|value| !value.is_finite())
61 || output_weights.iter().any(|value| !value.is_finite())
62 {
63 return Err(NetworkError::NonFinite);
64 }
65 Ok(Self {
66 feature_bias,
67 feature_weights,
68 output_weights,
69 output_bias,
70 })
71 }
72
73 pub fn quantize(&self) -> QuantizedNetwork {
74 QuantizedNetwork {
75 feature_bias: self
76 .feature_bias
77 .iter()
78 .map(|value| quantize_i16(*value, QA))
79 .collect(),
80 feature_weights: self
81 .feature_weights
82 .iter()
83 .map(|value| quantize_i16(*value, QA))
84 .collect(),
85 output_weights: self
86 .output_weights
87 .iter()
88 .map(|value| quantize_i16(*value, QB))
89 .collect(),
90 output_bias: quantize_i32(self.output_bias, QA * QB),
91 }
92 }
93
94 pub fn evaluate(&self, position: &Position) -> f32 {
95 let mut accumulators = [self.feature_bias.clone(), self.feature_bias.clone()];
96 for square in Square::all() {
97 let Some(piece) = position.piece_at(square) else {
98 continue;
99 };
100 for perspective in Color::ALL {
101 let feature = feature_index(piece, square, perspective);
102 let weights = &self.feature_weights[feature * HIDDEN..(feature + 1) * HIDDEN];
103 for (value, weight) in accumulators[perspective.index()].iter_mut().zip(weights) {
104 *value += weight;
105 }
106 }
107 }
108 let us = position.side_to_move().index();
109 let them = position.side_to_move().other().index();
110 let mut output = self.output_bias;
111 for (lane, weight) in accumulators[us]
112 .iter()
113 .chain(&accumulators[them])
114 .zip(&self.output_weights)
115 {
116 output += lane.clamp(0.0, 1.0) * weight;
117 }
118 output
119 }
120}
121
122#[derive(Debug, Clone, PartialEq, Eq)]
124pub struct QuantizedNetwork {
125 feature_bias: Vec<i16>,
126 feature_weights: Vec<i16>,
127 output_weights: Vec<i16>,
128 output_bias: i32,
129}
130
131impl QuantizedNetwork {
132 pub fn from_bytes(bytes: &[u8]) -> Result<Self, NetworkError> {
134 if bytes.len() < HEADER_BYTES {
135 return Err(NetworkError::Truncated);
136 }
137 if bytes[..8] != MAGIC {
138 return Err(NetworkError::Magic);
139 }
140 let version = read_u16(bytes, 8)?;
141 if version != VERSION {
142 return Err(NetworkError::Version(version));
143 }
144 if usize::from(read_u16(bytes, 10)?) != FEATURE_COUNT
145 || usize::from(read_u16(bytes, 12)?) != HIDDEN
146 {
147 return Err(NetworkError::Dimensions);
148 }
149 if bytes[14] != ACTIVATION_CRELU {
150 return Err(NetworkError::Activation(bytes[14]));
151 }
152 if i32::from(read_u16(bytes, 16)?) != QA || i32::from(read_u16(bytes, 18)?) != QB {
153 return Err(NetworkError::Scale);
154 }
155 let payload_len = read_u32(bytes, 20)? as usize;
156 if payload_len != PAYLOAD_BYTES || bytes.len() != HEADER_BYTES + payload_len {
157 return Err(NetworkError::Dimensions);
158 }
159 let payload = &bytes[HEADER_BYTES..];
160 let expected_checksum = read_u64(bytes, 24)?;
161 let actual_checksum = fnv1a(payload);
162 if actual_checksum != expected_checksum {
163 return Err(NetworkError::Checksum {
164 expected: expected_checksum,
165 actual: actual_checksum,
166 });
167 }
168
169 let mut cursor = 0;
170 let feature_bias = read_i16s(payload, &mut cursor, HIDDEN)?;
171 let feature_weights = read_i16s(payload, &mut cursor, FEATURE_COUNT * HIDDEN)?;
172 let output_weights = read_i16s(payload, &mut cursor, OUTPUT_INPUTS)?;
173 let output_bias = read_i32(payload, cursor)?;
174 cursor += 4;
175 if cursor != payload.len() {
176 return Err(NetworkError::Dimensions);
177 }
178 Ok(Self {
179 feature_bias,
180 feature_weights,
181 output_weights,
182 output_bias,
183 })
184 }
185
186 pub fn to_bytes(&self) -> Vec<u8> {
188 let mut payload = Vec::with_capacity(PAYLOAD_BYTES);
189 for value in self
190 .feature_bias
191 .iter()
192 .chain(&self.feature_weights)
193 .chain(&self.output_weights)
194 {
195 payload.extend_from_slice(&value.to_le_bytes());
196 }
197 payload.extend_from_slice(&self.output_bias.to_le_bytes());
198 debug_assert_eq!(payload.len(), PAYLOAD_BYTES);
199
200 let mut bytes = Vec::with_capacity(HEADER_BYTES + PAYLOAD_BYTES);
201 bytes.extend_from_slice(&MAGIC);
202 bytes.extend_from_slice(&VERSION.to_le_bytes());
203 bytes.extend_from_slice(&(FEATURE_COUNT as u16).to_le_bytes());
204 bytes.extend_from_slice(&(HIDDEN as u16).to_le_bytes());
205 bytes.push(ACTIVATION_CRELU);
206 bytes.push(0);
207 bytes.extend_from_slice(&(QA as u16).to_le_bytes());
208 bytes.extend_from_slice(&(QB as u16).to_le_bytes());
209 bytes.extend_from_slice(&(PAYLOAD_BYTES as u32).to_le_bytes());
210 bytes.extend_from_slice(&fnv1a(&payload).to_le_bytes());
211 debug_assert_eq!(bytes.len(), HEADER_BYTES);
212 bytes.extend_from_slice(&payload);
213 bytes
214 }
215
216 pub fn checksum(&self) -> u64 {
217 fnv1a(&self.to_bytes()[HEADER_BYTES..])
218 }
219
220 pub fn evaluate_refresh(&self, position: &Position) -> i32 {
221 Accumulator::refresh(position, self).evaluate(position.side_to_move(), self)
222 }
223}
224
225#[derive(Debug, Clone, PartialEq, Eq)]
227pub struct Accumulator {
228 values: [[i32; HIDDEN]; 2],
229}
230
231impl Accumulator {
232 pub fn refresh(position: &Position, network: &QuantizedNetwork) -> Self {
233 let mut bias = [0; HIDDEN];
234 for (lane, value) in bias.iter_mut().zip(&network.feature_bias) {
235 *lane = i32::from(*value);
236 }
237 let mut accumulator = Self {
238 values: [bias, bias],
239 };
240 for square in Square::all() {
241 if let Some(piece) = position.piece_at(square) {
242 accumulator.update_feature(network, piece, square, 1);
243 }
244 }
245 accumulator
246 }
247
248 pub fn apply(&mut self, network: &QuantizedNetwork, delta: &FeatureDelta) {
249 for change in delta.as_slice() {
250 self.update_feature(network, change.piece, change.square, i32::from(change.sign));
251 }
252 }
253
254 pub fn revert(&mut self, network: &QuantizedNetwork, delta: &FeatureDelta) {
255 for change in delta.as_slice().iter().rev() {
256 self.update_feature(
257 network,
258 change.piece,
259 change.square,
260 -i32::from(change.sign),
261 );
262 }
263 }
264
265 pub fn evaluate(&self, side_to_move: Color, network: &QuantizedNetwork) -> i32 {
266 let us = side_to_move.index();
267 let them = side_to_move.other().index();
268 let mut sum = i64::from(network.output_bias);
269 for (lane, weight) in self.values[us]
270 .iter()
271 .chain(&self.values[them])
272 .zip(&network.output_weights)
273 {
274 let activated = (*lane).clamp(0, QA);
275 sum += i64::from(activated) * i64::from(*weight);
276 }
277 rounded_division(sum, i64::from(QA * QB)) as i32
278 }
279
280 pub fn perspective(&self, perspective: Color) -> &[i32] {
281 &self.values[perspective.index()]
282 }
283
284 fn update_feature(
285 &mut self,
286 network: &QuantizedNetwork,
287 piece: Piece,
288 square: Square,
289 sign: i32,
290 ) {
291 for perspective in Color::ALL {
292 let feature = feature_index(piece, square, perspective);
293 let weights = &network.feature_weights[feature * HIDDEN..(feature + 1) * HIDDEN];
294 for (value, weight) in self.values[perspective.index()].iter_mut().zip(weights) {
295 *value += sign * i32::from(*weight);
296 }
297 }
298 }
299}
300
301#[derive(Debug, Clone, PartialEq, Eq)]
303pub struct FeatureDelta {
304 changes: [FeatureChange; Self::CAPACITY],
305 len: u8,
306}
307
308impl FeatureDelta {
309 const CAPACITY: usize = 5;
310
311 pub fn from_move(position: &Position, mv: Move) -> Result<Self, &'static str> {
312 let moved = position
313 .piece_at(mv.from())
314 .ok_or("NNUE delta move has no source piece")?;
315 if moved.color != position.side_to_move() {
316 return Err("NNUE delta move belongs to the wrong side");
317 }
318 let mut delta = Self {
319 changes: [FeatureChange::PLACEHOLDER; Self::CAPACITY],
320 len: 0,
321 };
322 delta.push(FeatureChange::remove(moved, mv.from()));
323
324 match mv.kind() {
325 MoveKind::EnPassant => {
326 let captured_square = mv
327 .to()
328 .offset(0, -moved.color.pawn_step())
329 .ok_or("en-passant capture square is outside the board")?;
330 let captured = position
331 .piece_at(captured_square)
332 .ok_or("en-passant delta has no captured pawn")?;
333 delta.push(FeatureChange::remove(captured, captured_square));
334 }
335 MoveKind::Normal | MoveKind::Promotion(_) => {
336 if let Some(captured) = position.piece_at(mv.to()) {
337 delta.push(FeatureChange::remove(captured, mv.to()));
338 }
339 }
340 MoveKind::CastleKingSide | MoveKind::CastleQueenSide => {}
341 }
342
343 let placed = Piece::new(moved.color, mv.promotion().unwrap_or(moved.kind));
344 delta.push(FeatureChange::add(placed, mv.to()));
345
346 match mv.kind() {
347 MoveKind::CastleKingSide => {
348 let rank = moved.color.home_rank();
349 let from = Square::from_file_rank(7, rank);
350 let to = Square::from_file_rank(5, rank);
351 let rook = position
352 .piece_at(from)
353 .ok_or("king-side castle delta has no rook")?;
354 delta.push(FeatureChange::remove(rook, from));
355 delta.push(FeatureChange::add(rook, to));
356 }
357 MoveKind::CastleQueenSide => {
358 let rank = moved.color.home_rank();
359 let from = Square::from_file_rank(0, rank);
360 let to = Square::from_file_rank(3, rank);
361 let rook = position
362 .piece_at(from)
363 .ok_or("queen-side castle delta has no rook")?;
364 delta.push(FeatureChange::remove(rook, from));
365 delta.push(FeatureChange::add(rook, to));
366 }
367 MoveKind::Normal | MoveKind::EnPassant | MoveKind::Promotion(_) => {}
368 }
369 Ok(delta)
370 }
371
372 pub fn changes(&self) -> impl ExactSizeIterator<Item = (Piece, Square, i8)> + '_ {
373 self.as_slice()
374 .iter()
375 .map(|change| (change.piece, change.square, change.sign))
376 }
377
378 fn push(&mut self, change: FeatureChange) {
379 debug_assert!((self.len as usize) < Self::CAPACITY);
380 self.changes[self.len as usize] = change;
381 self.len += 1;
382 }
383
384 fn as_slice(&self) -> &[FeatureChange] {
385 &self.changes[..self.len as usize]
386 }
387}
388
389#[derive(Debug, Clone, Copy, PartialEq, Eq)]
390struct FeatureChange {
391 piece: Piece,
392 square: Square,
393 sign: i8,
394}
395
396impl FeatureChange {
397 const PLACEHOLDER: Self =
398 Self::remove(Piece::new(Color::White, PieceKind::Pawn), Square::new(0));
399
400 const fn add(piece: Piece, square: Square) -> Self {
401 Self {
402 piece,
403 square,
404 sign: 1,
405 }
406 }
407
408 const fn remove(piece: Piece, square: Square) -> Self {
409 Self {
410 piece,
411 square,
412 sign: -1,
413 }
414 }
415}
416
417pub const fn feature_index(piece: Piece, square: Square, perspective: Color) -> usize {
421 let relative_color = if piece.color as u8 == perspective as u8 {
422 0
423 } else {
424 1
425 };
426 let relative_square = match perspective {
427 Color::White => square.index(),
428 Color::Black => square.index() ^ 56,
429 };
430 (relative_color * 6 + piece.kind.index()) * 64 + relative_square
431}
432
433#[derive(Debug, Clone, PartialEq, Eq)]
434pub enum NetworkError {
435 Truncated,
436 Magic,
437 Version(u16),
438 Dimensions,
439 Activation(u8),
440 Scale,
441 Checksum { expected: u64, actual: u64 },
442 NonFinite,
443}
444
445impl fmt::Display for NetworkError {
446 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
447 match self {
448 Self::Truncated => f.write_str("network file is truncated"),
449 Self::Magic => f.write_str("network magic does not match GAINNUE"),
450 Self::Version(version) => write!(f, "unsupported network version {version}"),
451 Self::Dimensions => f.write_str("network dimensions or payload length do not match"),
452 Self::Activation(activation) => {
453 write!(f, "unsupported network activation {activation}")
454 }
455 Self::Scale => f.write_str("network quantization scales do not match"),
456 Self::Checksum { expected, actual } => write!(
457 f,
458 "network checksum mismatch: expected {expected:016x}, got {actual:016x}"
459 ),
460 Self::NonFinite => f.write_str("float network contains a non-finite value"),
461 }
462 }
463}
464
465impl std::error::Error for NetworkError {}
466
467fn quantize_i16(value: f32, scale: i32) -> i16 {
468 let scaled = (value * scale as f32).round();
469 if scaled < i16::MIN as f32 {
470 i16::MIN
471 } else if scaled > i16::MAX as f32 {
472 i16::MAX
473 } else {
474 scaled as i16
475 }
476}
477
478fn quantize_i32(value: f32, scale: i32) -> i32 {
479 let scaled = (value * scale as f32).round();
480 if scaled < i32::MIN as f32 {
481 i32::MIN
482 } else if scaled > i32::MAX as f32 {
483 i32::MAX
484 } else {
485 scaled as i32
486 }
487}
488
489const fn rounded_division(numerator: i64, denominator: i64) -> i64 {
490 if numerator >= 0 {
491 (numerator + denominator / 2) / denominator
492 } else {
493 -((-numerator + denominator / 2) / denominator)
494 }
495}
496
497fn fnv1a(bytes: &[u8]) -> u64 {
498 let mut hash = 0xcbf2_9ce4_8422_2325;
499 for byte in bytes {
500 hash ^= u64::from(*byte);
501 hash = hash.wrapping_mul(0x100_0000_01b3);
502 }
503 hash
504}
505
506fn read_u16(bytes: &[u8], offset: usize) -> Result<u16, NetworkError> {
507 let value = bytes
508 .get(offset..offset + 2)
509 .ok_or(NetworkError::Truncated)?;
510 Ok(u16::from_le_bytes([value[0], value[1]]))
511}
512
513fn read_u32(bytes: &[u8], offset: usize) -> Result<u32, NetworkError> {
514 let value = bytes
515 .get(offset..offset + 4)
516 .ok_or(NetworkError::Truncated)?;
517 Ok(u32::from_le_bytes([value[0], value[1], value[2], value[3]]))
518}
519
520fn read_u64(bytes: &[u8], offset: usize) -> Result<u64, NetworkError> {
521 let value = bytes
522 .get(offset..offset + 8)
523 .ok_or(NetworkError::Truncated)?;
524 Ok(u64::from_le_bytes([
525 value[0], value[1], value[2], value[3], value[4], value[5], value[6], value[7],
526 ]))
527}
528
529fn read_i32(bytes: &[u8], offset: usize) -> Result<i32, NetworkError> {
530 let value = bytes
531 .get(offset..offset + 4)
532 .ok_or(NetworkError::Truncated)?;
533 Ok(i32::from_le_bytes([value[0], value[1], value[2], value[3]]))
534}
535
536fn read_i16s(bytes: &[u8], cursor: &mut usize, count: usize) -> Result<Vec<i16>, NetworkError> {
537 let byte_count = count.checked_mul(2).ok_or(NetworkError::Dimensions)?;
538 let values = bytes
539 .get(*cursor..*cursor + byte_count)
540 .ok_or(NetworkError::Truncated)?;
541 let parsed = values
542 .chunks_exact(2)
543 .map(|bytes| i16::from_le_bytes([bytes[0], bytes[1]]))
544 .collect();
545 *cursor += byte_count;
546 Ok(parsed)
547}