Skip to content

README.md

Latest commit

 

History

History
232 lines (188 loc) · 8.06 KB

README.md

File metadata and controls

232 lines (188 loc) · 8.06 KB

OpusChess - UCI Chess Engine

Python License Release

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

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

Stage 3: Advanced Optimizations

  1. Aspiration Windows — narrowing the alpha-beta window
  2. Static Exchange Evaluation (SEE) — fast capture evaluation
  3. Futility Pruning — pruning unpromising quiet moves
  4. Check Extensions — extending search on checks
  5. Internal Iterative Deepening (IID) — TT move search

Stage 4: Enhanced Evaluation

  1. Pawn Structure — doubled, isolated, passed, chains
  2. King Safety — pawn shield, open files
  3. Piece Activity — bishop pair, rooks on 7th, open files
  4. Mobility — counting available squares for pieces
  5. Center Control — bonus for central pawns

Stage 5: Endgame Knowledge

  1. KQ vs K — Queen vs King
  2. KR vs K — Rook vs King
  3. KBN vs K — Bishop + Knight vs King
  4. KP vs K — Square rule, opposition
  5. KR vs KP — Rook vs Pawn

Stage 6: UCI Extensions

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

Stage 7: Advanced Algorithms

  1. Razoring — aggressive pruning at low depths
  2. Reverse Futility Pruning — Static Null Move Pruning
  3. Late Move Pruning (LMP) — pruning late quiet moves
  4. Probcut — early cutoffs at high depths
  5. Singular Extensions — extensions for singularly good moves
  6. 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