# official-stockfish/nnue-pytorch architecture

> Architecture diagram of the GitHub repository official-stockfish/nnue-pytorch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/official-stockfish/nnue-pytorch
- Repository: https://github.com/official-stockfish/nnue-pytorch

## Overview

##### Project Type Analysis
This is a specialized machine learning training framework for chess evaluation networks, specifically NNUE networks used in Stockfish chess engine. The project combines Python-based training infrastructure with C++ performance-critical components.

##### Main Components

a) Data Pipeline Components:
- Training Data Loader (C++)
- High-performance data streaming component
- NNUE training data formats and streams
- Feature Transformers
- Different feature types (HalfKA, HalfKAv2, HalfKP)
- Feature block processing

b) Training Infrastructure:
- Python Training Framework
- Model architecture
- Feature processing
- Training loop
- Optimization Components
- Ranger optimizer
- Loss functions
- Performance monitoring

c) Evaluation and Testing:
- Game Playing Infrastructure
- Model Validation
- Performance Analysis

**┌─────────────────────────────────────────┐**
- Training Pipeline            │
- ┬───────────────────────┤
- Data Loading   │   Feature Processing  │
- (C++)       │      (Python)         │
- ┴───────────────────────┘
- ▼                 ▼
**┌─────────────────────────────────────────┐**
- Neural Network Training         │
- ┤
- Model Architecture                   │
- Optimization (Ranger)                │
- Training Loop                        │
- ┘
- ▼
**┌─────────────────────────────────────────┐**
- Evaluation & Testing            │
- ┤
- Game Playing                         │
- Model Validation                     │
- Performance Analysis                 │
- ┘

##### Detailed Component Representation

- Rectangles: Main processing components
- Hexagons: Feature transformers
- Diamonds: Decision points

- Blue: Python components
- Green: C++ components
- Orange: Data storage
- Purple: Neural network components

##### Important Details

a) Data Flow:
- How training data moves from the C++ loader to Python
- Feature transformation pipeline
- Demonstrate the training loop flow

b) Integration Points:
- C++/Python interface
- Model checkpoint saving/loading
- Evaluation integration with Stockfish

c) Configuration and Management:
- Training parameters
- Model architecture variations
- Evaluation metrics

##### Technical Specifications

- Required Python version (3.7+)
- C++ compiler requirements (GCC 9.2+)
- CUDA/GPU requirements
- External dependencies (CMake, Make)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Data_Pipeline
        DataGen["Data Generation"]
        DataLoader["Training Data Loader (C++)"]
        DataFormats["NNUE Data Formats"]
        DataStream["Data Stream Handler"]
        
        DataGen --> DataLoader
        DataLoader --> DataFormats
        DataFormats --> DataStream
    end

    subgraph Feature_Processing
        FT["Feature Transformer"]
        HalfKA["HalfKA Features"]
        HalfKAv2["HalfKAv2 Features"]
        HalfKP["HalfKP Features"]
        FB["Feature Block"]
        FS["Feature Set"]
        
        FT --> HalfKA & HalfKAv2 & HalfKP
        HalfKA & HalfKAv2 & HalfKP --> FB
        FB --> FS
    end

    subgraph Training_Infrastructure
        Model["Model Architecture"]
        Train["Training Framework"]
        Optimizer["Ranger Optimizer"]
        Serial["Model Serialization"]
        
        Model --> Train
        Optimizer --> Train
        Train --> Serial
    end

    subgraph Evaluation_Testing
        Games["Game Playing"]
        CrossCheck["Cross Check Eval"]
        Visualize["Visualization"]
        PerfAnalysis["Performance Analysis"]
        
        Games --> CrossCheck
        CrossCheck --> Visualize
        CrossCheck --> PerfAnalysis
    end

    DataStream --> FT
    FS --> Model
    Serial --> Games

    %% Click events for component mapping
    click DataGen "https://github.com/official-stockfish/nnue-pytorch/blob/master/scripts/gensfen.sh"
    click DataLoader "https://github.com/official-stockfish/nnue-pytorch/blob/master/training_data_loader.cpp"
    click DataFormats "https://github.com/official-stockfish/nnue-pytorch/blob/master/lib/nnue_training_data_formats.h"
    click DataStream "https://github.com/official-stockfish/nnue-pytorch/blob/master/lib/nnue_training_data_stream.h"
    click FT "https://github.com/official-stockfish/nnue-pytorch/blob/master/feature_transformer.py"
    click HalfKA "https://github.com/official-stockfish/nnue-pytorch/blob/master/halfka.py"
    click HalfKAv2 "https://github.com/official-stockfish/nnue-pytorch/blob/master/halfka_v2.py"
    click HalfKP "https://github.com/official-stockfish/nnue-pytorch/blob/master/halfkp.py"
    click FB "https://github.com/official-stockfish/nnue-pytorch/blob/master/feature_block.py"
    click FS "https://github.com/official-stockfish/nnue-pytorch/blob/master/feature_set.py"
    click Model "https://github.com/official-stockfish/nnue-pytorch/blob/master/model.py"
    click Train "https://github.com/official-stockfish/nnue-pytorch/blob/master/train.py"
    click Optimizer "https://github.com/official-stockfish/nnue-pytorch/blob/master/ranger.py"
    click Serial "https://github.com/official-stockfish/nnue-pytorch/blob/master/serialize.py"
    click Games "https://github.com/official-stockfish/nnue-pytorch/blob/master/run_games.py"
    click CrossCheck "https://github.com/official-stockfish/nnue-pytorch/blob/master/cross_check_eval.py"
    click Visualize "https://github.com/official-stockfish/nnue-pytorch/blob/master/visualize.py"
    click PerfAnalysis "https://github.com/official-stockfish/nnue-pytorch/blob/master/perf_sigmoid_fitter.py"

    classDef cpp fill:#90EE90
    classDef python fill:#87CEEB
    classDef data fill:#FFA500
    classDef eval fill:#DDA0DD

    class DataLoader,DataFormats,DataStream cpp
    class FT,HalfKA,HalfKAv2,HalfKP,FB,FS,Model,Train,Optimizer,Serial python
    class DataGen,Games,CrossCheck,Visualize,PerfAnalysis eval
    class Data_Pipeline,Feature_Processing,Training_Infrastructure,Evaluation_Testing data
```
