How rn5f107s2/molybdenum works
1. What this repository is
- Molybdenum is a standalone C++ chess engine.
- Its runtime architecture is centered on a single executable that speaks UCI (Universal Chess Interface) so it can be driven by a GUI like cutechess or by direct CLI commands.
2. Top-level execution flow
- main.cpp is the entry point.
- It initializes engine state, then hands control to the UCI command loop.
- From there, the engine alternates between:
- receiving position/setup commands,
- starting a search on demand,
- and emitting UCI-style info/bestmove output.
3. Protocol and command handling boundary
- UCI.cpp, UCI.h, UCIOptions.cpp, and UCIOptions.h form the front door of the engine.
- This layer parses incoming text commands such as position, go, bench, eval, and d.
- It is the boundary between external clients and internal chess logic.
4. Board state and move representation
- Position.cpp/.h, Move.h, BitStuff.h, and Constants.h define the engine’s core chess state and low-level move/board abstractions.
- This is the central data model that everything else reads from and writes to: search, evaluation, move generation, and perft.
5. Move generation subsystem
- Movegen.h, MagicBitboards.h, and Move.h implement legal/pseudo-legal move generation.
- The presence of magic bitboards indicates a bitboard-based move generator optimized for sliding pieces.
- This subsystem supplies candidate moves to the searcher and is also likely used by perft and test/bench paths.
6. Search subsystem
- search.cpp/.h, searchUtil.h, Movepicker.h, Transpositiontable.cpp/.h, and timemanagement.h/timemanagment.cpp make up the engine’s thinking core.
- Search consumes a Position, generates and orders moves, consults the transposition table, and applies pruning/selection heuristics.
- It is responsible for producing principal variation, scores, node counts, and the final best move.
7. Evaluation subsystem
- eval.h, PSQT.h, nnue.cpp/.h, simd.h, and src/incbin/ are the engine’s evaluation layer.
- README states the engine uses an NNUE-style neural network with architecture (768->32)x2->1.
- PSQT suggests some positional scoring support alongside the NNUE path, while simd.h likely provides vectorized acceleration for evaluation and/or move processing.
8. Performance infrastructure
- Transpositiontable.* is a major cache used by search to avoid re-evaluating positions.
- thread.cpp/.h indicates the engine supports multi-threaded search, with shared search state and per-thread coordination.
- bench.h and Perft.h support diagnostics and performance validation rather than playing strength directly.
9. Time management
- timemanagement.h and timemanagment.cpp control how long the engine searches before stopping.
- This layer converts UCI limits like movetime, depth, nodes, or infinite into search-stop conditions.
10. Auxiliary tools and training support
- src/Datagen/Datagen.cpp/.h and tune.h suggest support for self-play data generation and parameter tuning.
- src/util/preprocess.cpp likely supports offline preprocessing or code/data generation for these workflows.
- These paths are separate from the main UCI search loop and are oriented toward engine development rather than game play.
11. Output and diagnostic paths
- The README documents extra engine commands such as bench, d, and eval.
- These are implemented through the UCI-facing command layer but route into internal diagnostics:
- board display/state inspection,
- static evaluation reporting,
- fixed-depth benchmark searches.
12. Build and integration surface
- The repo is a native C++ project built from source, with a Makefile and GitHub Actions workflow under .github/workflows/build.yaml.
- No web backend, database, or network service is part of the architecture; the engine is primarily an embedded compute process driven by text protocol input.
Main entry points: search.cpp Search · UCI.cpp UCI loop · Position.cpp Board state · Movegen.h Movegen
Components 20
Engine runtime
Main executable, UCI protocol boundary, and search/evaluation core.
- Main · Program entry that initializes the engine and starts command handling.
src/main.cpp - UCI loop · Text command boundary for position, go, bench, eval, and debug commands.
src/UCI.cpp - UCI options · Parses and stores engine option settings exposed through UCI.
src/UCIOptions.cpp - Search · Main thinking loop that scores positions, selects moves, and produces bestmove output.
src/search.cpp - Move ordering · Move picker and search utilities used to rank and filter candidate moves.
src/Movepicker.h - TT cache · Transposition table used to reuse prior search results and speed up pruning.
src/Transpositiontable.cpp - Time control · Converts UCI limits into stop conditions for iterative search.
src/timemanagment.cpp - Threading · Coordinates multi-threaded search execution and shared state.
src/thread.cpp - Evaluation · Static evaluation path combining neural and positional scoring.
src/eval.h - NNUE · Neural-network evaluation implementation and feature pipeline.
src/nnue.cpp
Core chess model
Board state, move representation, and move generation primitives.
- Board state · Central chess position representation and state transitions.
src/Position.cpp - Move data · Move encoding and low-level board/move constants.
src/Move.h - Bitboards · Bit manipulation helpers and constants used throughout chess logic.
src/BitStuff.h - Movegen · Legal and pseudo-legal move generation built on bitboards and magic tables.
src/Movegen.h - Magic tables · Precomputed sliding-piece attack generation support.
src/MagicBitboards.h
Support tooling
Diagnostics, tuning, data generation, and build/integration surface.
- Perft · Move-tree counting used to validate correctness and generator behavior.
src/Perft.h - Bench · Fixed workload benchmark path exposed through the command interface.
src/bench.h - Datagen · Self-play and data-generation support for engine development.
src/Datagen/Datagen.cpp - Preprocess · Offline preprocessing utility supporting training or data workflows.
src/util/preprocess.cpp - Build · Native build and CI integration for compiling and validating the engine.
Makefile
Connections 26
- Main → UCI loop: starts · Main hands control to the UCI command loop.
- UCI loop → UCI options: options · UCI exposes and updates engine settings.
- UCI loop → Search: go/search · Search is launched in response to go-like commands.
- UCI loop → Board state: position · Command layer creates or mutates board state.
- UCI loop → Perft: perft · Diagnostic commands can route to move-tree validation.
- UCI loop → Bench: bench · Benchmark command triggers fixed-depth search workload.
- UCI loop → Evaluation: eval · Evaluation diagnostics query the static eval layer.
- Search → Move ordering: orders · Search uses move ordering heuristics.
- Search → TT cache: reads/writes · Search probes and stores positions in the transposition table.
- Search → Time control: stops by · Time control determines when search must stop.
- Search → Threading: parallelizes · Search can run across multiple threads.
- Search → Board state: consumes · Search operates on the current position.
- Search → Evaluation: scores · Leaf or quiescent positions are evaluated.
- Evaluation → NNUE: uses · Evaluation includes the NNUE path.
- Board state → Move data: encodes · Board state relies on the engine's move representation.
- Board state → Bitboards: bitboards · Position internals use bitboard primitives.
- Movegen → Board state: generates for · Move generation derives legal moves from position state.
- Movegen → Move data: emits · Generated moves use the shared move encoding.
- Movegen → Magic tables: sliding attacks · Magic bitboards supply fast rook/bishop attack lookups.
- Perft → Movegen: validates · Perft depends on the move generator for tree counts.
- Bench → Search: drives · Benchmarking exercises the search core.
- Datagen → Board state: samples · Data generation works from engine positions.
- Datagen → Search: self-play · Generated data can be produced via engine search.
- Preprocess → Datagen: supports · Preprocessing feeds the data-generation workflow.
- Build → Main: builds · Build surface compiles the executable entrypoint.
- Build → Search: integrates · CI and build tooling validate the search engine.