# willching01/pingu architecture

> Architecture diagram of the GitHub repository willching01/pingu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/willching01/pingu
- Repository: https://github.com/willching01/pingu

## Overview

##### Project Type and Purpose
- Pingu is a specialized chess engine designed to process UCI commands, generate chess moves, perform complex search algorithms (like iterative deepening, alpha-beta pruning variants, and parallel search with Lazy SMP) and employ a neural network (NNUE) for evaluation.
- The project also includes components to train and utilize NNUE models, signified by the nnue/model and nnue/dataset directories.

##### Break Down the File Structure into Main Components
a. Engine Core & UCI Interface:
- main.cpp serves as the entry point handling UCI command processing.
- /uci.h and related headers define the communication protocol.
b. Board Representation & Move Generation:
- Files in include such as board.h, bitboard.h, pawn.h, knight.h, king.h, slider.h, and movepicker.h suggest a detailed representation of game rules and move generation logic.
c. Search Engine:
- The include files related to search (search.h, killer.h, transposition.h, and thread.h) outline the implementation of various search techniques, including iterative deepening, alpha-beta variants, and parallel search.
d. Evaluation Module (NNUE Integration):
- /evaluation.h and include/nnue.h, together with the nnue directory (containing dataset, model code, training, and export scripts), indicate a significant NNUE component.
- This part of the system has two aspects: one for running inference during a game (with quantized weights and AVX2 intrinsics), and one for model training using PyTorch.
e. Testing and Continuous Integration:
- The testing directory holds scripts (engine.py, fen_check.py, perft_check.py, etc.) that are used to unit-, integration-, and performance-test different engine aspects.
- The .github/workflows files and Makefile indicate automated building, testing, and linting via CI/CD pipelines.
f. Documentation:
- The docs directory and README provide insights into NNUE tuning and evaluation, establishing guidelines for NNUE model training and performance assessment.

##### Out Relationships and Interactions
- UCI Command Processing: The engine (main.cpp) receives commands from a UCI-compatible GUI. Commands are parsed and then dispatched to the move generation or search modules.
- Move Generation & Board Management: Once a move or position command is received, the board representation (bitboard, board.h, etc.) and move generation components determine possible moves.
- Search Engine: With the generated move list and board state, the search algorithm (with iterative deepening, various pruning techniques, and parallel search) identifies the best move. Internal components like the transposition table and move ordering logic interact closely to optimize the search.
- Evaluation via NNUE: During search, the engine utilizes the evaluation modules (NNUE and traditional evaluation functions) to assess board positions. This module accesses the pre-trained NNUE model which might require running specific functions (e.g., from nnue/model/model.py or imported C++ functions in include/nnue.h).
- Testing Loop: The testing frameworks validate the correctness and performance of move generation, search, and evaluation through several test scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% UCI Interface
    subgraph "UCI Interface"
        UCI_main["main.cpp"]:::uci
        UCI_uci["uci.h"]:::uci
    end

    %% Board & Move Generation
    subgraph "Board & Move Generation"
        Board["board.h"]:::board
        Bitboard["bitboard.h"]:::board
        Pawn["pawn.h"]:::board
        Knight["knight.h"]:::board
        King["king.h"]:::board
        Slider["slider.h"]:::board
        MovePicker["movepicker.h"]:::board
    end

    %% Search Engine
    subgraph "Search Engine"
        Search["search.h"]:::search
        Killer["killer.h"]:::search
        Transposition["transposition.h"]:::search
        Thread["thread.h"]:::search
    end

    %% Evaluation Module (NNUE Integration)
    subgraph "Evaluation Module (NNUE Integration)"
        Eval["evaluation.h"]:::eval
        NNUE["nnue.h"]:::eval
        NNUEModel["nnue/model"]:::eval
        NNUEUtils["nnue/include/utils.h"]:::eval
    end

    %% NNUE Training & Model Components
    subgraph "NNUE Training & Model Components"
        NNUEData["nnue/dataset"]:::training
        NNUEModelTrain["nnue/model (Training)"]:::training
    end

    %% Testing & CI Infrastructure
    subgraph "Testing & CI Infrastructure"
        Test["testing"]:::test
        Workflows[".github/workflows"]:::test
        TestMakefile["Makefile"]:::test
        TestReadme["README.md"]:::test
    end

    %% Documentation & Configurations
    subgraph "Documentation & Configurations"
        Docs["docs"]:::docs
        DocReadme["README.md"]:::docs
        DocMakefile["Makefile"]:::docs
    end

    %% High-Level Component Interactions
    UCI_main -->|"process_command"| Board
    Board -->|"generate_moves"| Search
    Search <-->|"evaluate"| Eval
    Eval -->|"return_decision"| UCI_main
    NNUEData -->|"provide_weights"| NNUEModel

    %% Testing connections from core modules
    UCI_main -->|"tested_by"| Test
    Board -->|"tested_by"| Test
    Search -->|"tested_by"| Test
    Eval -->|"tested_by"| Test
    NNUEData -->|"tested_by"| Test

    %% Documentation sync from Testing & CI
    Test -->|"docs_sync"| Docs

    %% Click Events for UCI Interface
    click UCI_main "https://github.com/willching01/pingu/blob/master/main.cpp"
    click UCI_uci "https://github.com/willching01/pingu/blob/master/include/uci.h"

    %% Click Events for Board & Move Generation
    click Board "https://github.com/willching01/pingu/blob/master/include/board.h"
    click Bitboard "https://github.com/willching01/pingu/blob/master/include/bitboard.h"
    click Pawn "https://github.com/willching01/pingu/blob/master/include/pawn.h"
    click Knight "https://github.com/willching01/pingu/blob/master/include/knight.h"
    click King "https://github.com/willching01/pingu/blob/master/include/king.h"
    click Slider "https://github.com/willching01/pingu/blob/master/include/slider.h"
    click MovePicker "https://github.com/willching01/pingu/blob/master/include/movepicker.h"

    %% Click Events for Search Engine
    click Search "https://github.com/willching01/pingu/blob/master/include/search.h"
    click Killer "https://github.com/willching01/pingu/blob/master/include/killer.h"
    click Transposition "https://github.com/willching01/pingu/blob/master/include/transposition.h"
    click Thread "https://github.com/willching01/pingu/blob/master/include/thread.h"

    %% Click Events for Evaluation Module
    click Eval "https://github.com/willching01/pingu/blob/master/include/evaluation.h"
    click NNUE "https://github.com/willching01/pingu/blob/master/include/nnue.h"
    click NNUEModel "https://github.com/willching01/pingu/tree/master/nnue/model"
    click NNUEUtils "https://github.com/willching01/pingu/blob/master/nnue/include/utils.h"

    %% Click Events for NNUE Training & Model Components
    click NNUEData "https://github.com/willching01/pingu/tree/master/nnue/dataset"
    click NNUEModelTrain "https://github.com/willching01/pingu/tree/master/nnue/model"

    %% Click Events for Testing & CI Infrastructure
    click Test "https://github.com/willching01/pingu/tree/master/testing"
    click Workflows "https://github.com/willching01/pingu/tree/master/.github/workflows"
    click TestMakefile "https://github.com/willching01/pingu/tree/master/Makefile"
    click TestReadme "https://github.com/willching01/pingu/blob/master/README.md"

    %% Click Events for Documentation & Configurations
    click Docs "https://github.com/willching01/pingu/tree/master/docs"
    click DocReadme "https://github.com/willching01/pingu/blob/master/README.md"
    click DocMakefile "https://github.com/willching01/pingu/tree/master/Makefile"

    %% Styles for Color Coding
    classDef uci fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef board fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef search fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef eval fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef training fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef test fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef docs fill:#D5F5E3,stroke:#117864,stroke-width:2px;
```
