Skip to main content

ai_chess/
nnue.rs

1//! A deliberately small, scalar NNUE foundation.
2//!
3//! The feature transformer is `768 → 128`. One shared transformer produces
4//! White- and Black-perspective accumulators; evaluation concatenates
5//! side-to-move first and applies one clipped-ReLU output head. The expensive
6//! first layer can be updated by adding/removing only the rows touched by a
7//! move.
8
9use 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;
16// This teaching net keeps scalar `i32` accumulators, so a finer transformer
17// scale is safe and materially reduces rounding error in a small trained net.
18pub 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/// Trainable floating-point form of the fixed tiny NNUE architecture.
37#[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/// Serialized integer form used by the runtime evaluator.
123#[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    /// Parses a versioned network and validates its dimensions and checksum.
133    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    /// Serializes the network in the versioned `GAINNUE` format.
187    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/// Incrementally maintainable pair of perspective accumulators.
226#[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/// Bounded set of NNUE feature changes caused by one chess move.
302#[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
417/// Shared feature transformer index, normalized into `perspective`'s view.
418///
419/// Feature planes are `[our P..K, their P..K]`, each in a1..h8 order.
420pub 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}