How yaneurao/yaneuraou works
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.