OpusChess - UCI Chess Engine

A pure Python chess engine with UCI protocol support.

🇷🇺 Русская версия (Russian version)

Features

Chess Rules (FIDE)

• ✅ All piece movements (pawn, knight, bishop, rook, queen, king)
• ✅ Castling (kingside O-O and queenside O-O-O)
• ✅ En passant capture
• ✅ Pawn promotion (to queen, rook, bishop, knight)
• ✅ Check, checkmate, stalemate
• ✅ 50-move rule
• ✅ Threefold repetition rule
• ✅ Insufficient material for checkmate

UCI Protocol

• ✅ uci - engine identification
• ✅ isready / readyok - readiness check
• ✅ ucinewgame - new game
• ✅ position startpos [moves ...] - starting position
• ✅ position fen <fen> [moves ...] - position from FEN
• ✅ go depth <n> - search to depth n
• ✅ stop - stop search
• ✅ quit - exit

Search Engine

• ✅ Minimax with Alpha-Beta pruning
• ✅ Iterative Deepening
• ✅ Quiescence search
• ✅ Move ordering (MVV-LVA)
• ✅ Piece-square tables for position evaluation
• ✅ Transposition Table (Zobrist hashing, 64MB cache)
• ✅ TT move ordering (best move from cache first)
• ✅ Null Move Pruning (skipping a move for cutoff)
• ✅ Late Move Reductions (reduced search depth for late moves)
• ✅ Killer Move Heuristic (remembering moves that caused beta-cutoffs)
• ✅ History Heuristic (statistics of successful moves)
• ✅ Principal Variation Search (PVS)
• ✅ Aspiration Windows (narrowing the alpha-beta window)
• ✅ Static Exchange Evaluation (SEE for capture evaluation)
• ✅ Futility Pruning (pruning unpromising moves)
• ✅ Check Extensions (search extensions on checks)
• ✅ Internal Iterative Deepening (IID for positions without a TT move)

UCI Options

• Hash — Transposition table size (1-1024 MB, default 64)
• Depth — Default search depth (1-30, default 6)
• Ponder — Enable ponder move output
• UseTranspositionTable — Enable/disable TT
• UseNullMove — Enable/disable Null Move Pruning
• UseLMR — Enable/disable Late Move Reductions
• UseIID — Enable/disable Internal Iterative Deepening
• UseRazoring — Enable/disable Razoring
• UseReverseFutility — Enable/disable Reverse Futility Pruning
• UseLMP — Enable/disable Late Move Pruning
• UseProbcut — Enable/disable Probcut
• UseSingularExtensions — Enable/disable Singular Extensions
• UseCountermove — Enable/disable Countermove Heuristic
• Clear Hash — Clear transposition table

Improved Position Evaluation

• ✅ Pawn structure (doubled, isolated, passed, chains)
• ✅ King safety (pawn shield, open files)
• ✅ Piece activity (bishop pair, rooks on open files, on the 7th rank)
• ✅ Piece mobility (knights, bishops, rooks, queen)
• ✅ Center control

Endgame Knowledge

• ✅ KQ vs K — Queen vs King (driving to the edge)
• ✅ KR vs K — Rook vs King (forced mate)
• ✅ KBN vs K — Bishop + Knight vs King
• ✅ KP vs K — Square rule, rook pawns
• ✅ KR vs KP — Rook vs Pawn

Running

python main.py

Statistics Output Example:

info depth 1 score cp 82 nodes 45 time 16 nps 2723 hashfull 0 pv e2e4
info depth 2 score cp 0 nodes 322 time 118 nps 2718 hashfull 0 pv d2d4 d7d5
info depth 3 score cp 69 nodes 971 time 368 nps 2635 hashfull 0 pv e2e4 d7d5 b1c3
info depth 4 score cp 0 nodes 4048 time 1544 nps 2621 hashfull 0 pv b1c3 e7e5 e2e4 b8c6
info depth 5 score cp 61 nodes 4751 time 2150 nps 2208 hashfull 2 pv g1f3 g8f6 b1c3 d7d5 d2d4
bestmove g1f3 ponder g8f6

Fields Explanation:

• depth — current search depth
• score cp — centipawn evaluation (+ indicates white is better)
• nodes — number of positions explored
• time — time in milliseconds
• nps — nodes per second (speed)
• hashfull — hash table occupancy (0-1000)
• pv — principal variation (best line of moves)
• ponder — expected opponent's response

After launching, the engine waits for UCI commands from stdin.

Usage with GUI

1. Open any UCI-compatible program (Arena, CuteChess, etc.)
2. Add the engine: point it to the main.py file
3. Start playing!

Console Usage Example

> uci
id name OpusChess 2.0
id author AI Assistant
option name Hash type spin default 64 min 1 max 1024
option name Depth type spin default 6 min 1 max 30
...
uciok

> isready
readyok

> position startpos
> go depth 5
info depth 1 score cp 82 nodes 45 time 16 nps 2723 hashfull 0 pv e2e4
...
bestmove g1f3 ponder g8f6

> quit

Project Structure

├── main.py              # Entry point
├── board.py             # Board representation, FEN, moves
├── move_generator.py    # Legal move generation
├── evaluation.py        # Position evaluation
├── search.py            # Best move search
├── uci.py               # UCI protocol implementation
└── README.md            # Documentation

Debug Commands

Additional commands (not part of standard UCI):

• d - display board in text format
• perft <depth> - node count (for testing)
• bench - performance benchmark

Development History

Sequence of improvements in chronological order:

Stage 1: Basic Implementation

1. Board Representation (board.py) — 64-element array, FEN parsing, make/unmake move
2. Move Generator (move_generator.py) — all legal FIDE moves
3. Basic Evaluation (evaluation.py) — material + piece-square tables
4. Search (Minimax) (search.py) — alpha-beta pruning
5. UCI Protocol (uci.py) — full UCI support

Stage 2: Search Optimizations

6. Transposition Table — Zobrist hashing, position caching
7. Null Move Pruning — skipping a move to force a cutoff
8. Late Move Reductions (LMR) — depth reduction for late moves
9. Killer Move Heuristic — remembering beta-cutoff moves
10. History Heuristic — successful move statistics
11. Principal Variation Search (PVS) — PV node optimization

Stage 3: Advanced Optimizations

12. Aspiration Windows — narrowing the alpha-beta window
13. Static Exchange Evaluation (SEE) — fast capture evaluation
14. Futility Pruning — pruning unpromising quiet moves
15. Check Extensions — extending search on checks
16. Internal Iterative Deepening (IID) — TT move search

Stage 4: Enhanced Evaluation

17. Pawn Structure — doubled, isolated, passed, chains
18. King Safety — pawn shield, open files
19. Piece Activity — bishop pair, rooks on 7th, open files
20. Mobility — counting available squares for pieces
21. Center Control — bonus for central pawns

Stage 5: Endgame Knowledge

22. KQ vs K — Queen vs King
23. KR vs K — Rook vs King
24. KBN vs K — Bishop + Knight vs King
25. KP vs K — Square rule, opposition
26. KR vs KP — Rook vs Pawn

Stage 6: UCI Extensions

27. UCI Options — configurable settings (Hash, Depth, flags)
28. Info callback — statistics output at each depth (depth, nodes, nps, pv, hashfull)
29. Contempt — draw score penalty in a winning position
30. Repetition avoidance — avoiding draw by repetition
31. Ponder move — outputting expected opponent response

Stage 7: Advanced Algorithms

32. Razoring — aggressive pruning at low depths
33. Reverse Futility Pruning — Static Null Move Pruning
34. Late Move Pruning (LMP) — pruning late quiet moves
35. Probcut — early cutoffs at high depths
36. Singular Extensions — extensions for singularly good moves
37. Countermove Heuristic — remembering best replies to moves

Performance

Comparison for depth 5 on the starting position:

Configuration	Nodes	Time	Speedup
All optimizations OFF	15,352	6.23s	1.0x
All optimizations ON	4,751	2.15s	2.9x

Node reduction: 69%

Requirements

• Python 3.8+
• No external dependencies

License

MIT License