# yaneurao/yaneuraou architecture

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

- Interactive diagram: https://gitdiagram.com/yaneurao/yaneuraou
- Repository: https://github.com/yaneurao/yaneuraou

## Overview

##### Project Type and Purpose
- This is a high-performance Shogi (Japanese chess) engine that is USI compliant. It is designed not only as a competitive game engine (with multiple tournament wins) but also as an educational tool.
- The README emphasizes advanced search techniques, evaluation functions (including NNUE, KPPT, KPP_KKPT), and support for multi-threaded and high-parallelism processing. It also outlines the capability for different sub-engines (such as dlshogi-engine, tanuki-mate-engine, etc.) and multiple build targets (Windows, Ubuntu, macOS, Android, WebAssembly).

##### Analyzing the File Structure
- Top-level Directories: Notice directories like “source”, “old_engines”, “docs”, “jni”, “script” – these segregate current production code, legacy engines, documentation, build scripts, and auxiliary tools.
- “source” contains the bulk of the current engine code. There are subdirectories dedicated to various modules:
– Engine routines (e.g. “engine” with several submodules such as yaneuraou-engine, dlshogi-engine, tanuki-mate-engine, etc.)
– Evaluation functions (“eval”), with separate submodules for deep learning integration (deep/nn, nnue components) and legacy evaluation function implementations.
– Book-related modules under “source/book” (for opening or policy book support).
– USI protocol implementation (usi.cpp, usi.h) to interact with external GUI or tournament environments.
- “old_engines” contains multiple legacy versions/modules, indicating the evolution of the engine and providing context for legacy support and comparability.
- “scripts” provide build configurations, analysis tools, and automation (e.g. bench.py, build scripts, docker/CI configurations).
- The presence of a Visual Studio solution file (YaneuraOu.sln) and numerous GitHub workflow files signifies cross-platform builds and continuous integration.

##### Key Components
a. Main modules/components:
– USI Interface Module: Handles input/output per the USI protocol.
– Core Engine Controller: Manages overall game logic and orchestrates the search.
– Search Modules: Incorporate the iterative deepening / alpha-beta algorithms; sub-components such as “yaneuraou-search.cpp” and specialized search variants (e.g., UctSearch, PvMateSearch).
– Evaluation Modules: Separate “eval” directory showing multiple evaluation strategies (traditional static evaluations and NNUE/deep learning based ones).
– Book Module: For opening moves and policy book handling, located in “source/book”.
– Learning Components: “learn” directory that includes learning tools and multi-think capabilities.
– Thread/Parallelism Manager: Handled in “thread.cpp”/ “thread.h” and the clustering modules (see “yo-cluster” which deals with engine clustering and negotiation).
– Legacy Engines: Represented by the “old_engines” folder that can be optionally included to show historical evolution or fallback components.
– Utility & Extra Components: Additional helper libraries under “extra” and “misc” functions.
– Build and Deployment Infrastructure: CI workflows (GitHub Actions) and platform-specific build scripts, which highlight multi-platform support.

b. Relationships and Interactions:
– The USI interface accepts commands that are passed to the Engine Controller.
– The Engine Controller dispatches tasks to the Search and Evaluation modules.
– The Search module uses iterative deepening and alpha-beta pruning, receives evaluation scores from the Evaluation module (which on occasion may use neural network based evaluations).
– The Book module may be used at game start or for specific opening analysis.
– The Thread Manager oversees and coordinates multi-thread execution across the search tree.
– Legacy engine components and additional evaluation/learning scripts interact as optional modules but are clearly separated from the primary production engine.

##### Architectural Patterns & Design Principles
- Modularity: The clear separation of responsibilities (protocol handling, search, evaluation, learning, book handling) is a central architectural design.
- Extensibility: Support for various sub-engines (dlshogi-engine, tanuki-mate-engine, user-engine, etc.) shows a pluggable design where adding a new search routine is straightforward.
- Cross-platform and CI: The use of platform-specific build scripts and continuous integration configurations demonstrates an emphasis on maintainability and scalability.
- Performance and Concurrency: Design choices to support high degrees of parallelism (e.g., 256-thread parallel search) and specialized hardware (NN modules, GPU-less deep learning using DirectML/TensorRT) should be highlighted.

– Clear and descriptive labels for each module (e.g., “USI Protocol Handler”, “Alpha-Beta Search Engine”, “NNUE Evaluation Module”).
- Incoming game commands and parameters from the UI/external interface entering via the USI module.
- Call relationships from the Engine Controller to Search and Evaluation modules.
- Data/feedback loops, especially from multi-threaded search components back to the controller.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Presentation/Communication Layer
    subgraph "Presentation/Communication Layer"
        USI_Interface["USI Protocol Handler"]:::presentation
    end

    %% Core Logic Layer
    subgraph "Core Logic Layer"
        EngineController["Core Engine Controller"]:::core
        PrimarySearch["Primary Search Module"]:::core
        SpecializedSearch["Specialized Search Modules"]:::core
        ThreadManager["Thread Manager"]:::core
    end

    %% Evaluation & Learning Layer
    subgraph "Evaluation & Learning Layer"
        EvalTraditional["Evaluation Module (Traditional)"]:::evaluation
        EvalNNUE["NNUE / Deep Evaluation"]:::evaluation
        Learning["Learning Components"]:::evaluation
    end

    %% Auxiliary Modules
    subgraph "Auxiliary Modules"
        BookModule["Book Module"]:::auxiliary
        LegacyEngines["Legacy Engines"]:::auxiliary
        UtilityExtra["Utility & Extra Components"]:::auxiliary
        BuildInfra["Build & Deployment Infrastructure"]:::build
    end

    %% Relationships
    USI_Interface -->|"receives_commands"| EngineController
    EngineController -->|"dispatches_search"| PrimarySearch
    EngineController -->|"dispatches_search"| SpecializedSearch
    EngineController -->|"manages_threads"| ThreadManager
    EngineController -->|"uses_eval"| EvalTraditional
    EngineController -->|"uses_NNUE"| EvalNNUE
    EngineController -->|"trains"| Learning
    EngineController -->|"uses_book"| BookModule
    EngineController -->|"fallback"| LegacyEngines
    EngineController -->|"calls_utilities"| UtilityExtra
    ThreadManager -->|"parallel_search"| PrimarySearch
    PrimarySearch -->|"evaluation"| EvalTraditional
    PrimarySearch -->|"evaluation"| EvalNNUE
    BuildInfra -->|"deployment"| EngineController

    %% Click Events
    click USI_Interface "https://github.com/yaneurao/yaneuraou/blob/master/source/usi.cpp"
    click USI_Interface "https://github.com/yaneurao/yaneuraou/blob/master/source/usi.h"

    click EngineController "https://github.com/yaneurao/yaneuraou/blob/master/source/engine.cpp"
    click EngineController "https://github.com/yaneurao/yaneuraou/blob/master/source/engine.h"

    click PrimarySearch "https://github.com/yaneurao/yaneuraou/blob/master/source/engine/yaneuraou-engine/yaneuraou-search.cpp"

    click SpecializedSearch "https://github.com/yaneurao/yaneuraou/tree/master/source/engine/dlshogi-engine"
    click SpecializedSearch "https://github.com/yaneurao/yaneuraou/blob/master/source/engine/tanuki-mate-engine/tanuki-mate-search.cpp"

    click EvalTraditional "https://github.com/yaneurao/yaneuraou/blob/master/source/eval/evaluate.cpp"

    click EvalNNUE "https://github.com/yaneurao/yaneuraou/tree/master/source/eval/deep"
    click EvalNNUE "https://github.com/yaneurao/yaneuraou/tree/master/source/eval/nnue"

    click Learning "https://github.com/yaneurao/yaneuraou/tree/master/source/learn"

    click ThreadManager "https://github.com/yaneurao/yaneuraou/blob/master/source/thread.cpp"
    click ThreadManager "https://github.com/yaneurao/yaneuraou/blob/master/source/thread.h"

    click BookModule "https://github.com/yaneurao/yaneuraou/tree/master/source/book"

    click LegacyEngines "https://github.com/yaneurao/yaneuraou/tree/master/old_engines"

    click UtilityExtra "https://github.com/yaneurao/yaneuraou/tree/master/source/extra"

    click BuildInfra "https://github.com/yaneurao/yaneuraou/tree/master/.github/workflows"
    click BuildInfra "https://github.com/yaneurao/yaneuraou/tree/master/script"

    %% Styles
    classDef presentation fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef core fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef evaluation fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef auxiliary fill:#F5CBA7,stroke:#AF601A,stroke-width:2px;
    classDef build fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
```
