| --- |
| language: en |
| license: cc-by-nc-4.0 |
| tags: |
| - chess |
| - chess-engine |
| - transformer |
| - from-scratch |
| - small-model |
| - mcts |
| --- |
| |
| # Parallax-Chess-Preview |
|
|
| A chess engine trained from scratch on a single laptop GPU (RTX 5060). Uses a 25.9M parameter transformer with Monte Carlo Tree Search (MCTS) for move selection. |
|
|
| ## What's Inside |
|
|
| - **25.9M param transformer** trained on 200K+ positions with Stockfish evaluations |
| - **Policy network**: predicts best move from board state (4352-class output covering all possible moves) |
| - **Value network**: evaluates positions in centipawns (trained on Stockfish depth-10 evaluations) |
| - **MCTS search**: looks ahead multiple moves using the neural network for evaluation |
| - **Custom chess tokenizer**: no external tokenizer needed — pure chess-aware encoding |
| - **Tkinter GUI**: interactive chess board with click-to-move interface |
|
|
| ## Performance |
|
|
| | Metric | Value | |
| |--------|-------| |
| | Parameters | 25.9M | |
| | Training data | 200K Stockfish-evaluated positions + 143K puzzles | |
| | Training time | ~2 hours on RTX 5060 | |
| | Policy loss | 8.47 → 2.50 (4352-class prediction) | |
| | Speed (greedy) | ~19 moves/sec | |
| | Speed (MCTS 200 sims) | ~2 moves/sec | |
| | Estimated ELO | ~800-1000 (greedy), ~1200-1500 (MCTS) | |
| | Opens with | e2e4, Nf3, Ruy Lopez — real chess openings | |
|
|
| ## Quick Start |
|
|
| ### Greedy (fast, weaker) |
| ```python |
| from train_v3 import ParallaxChessV3 |
| import chess |
| |
| model = ParallaxChessV3.load("model.pt") |
| board = chess.Board() |
| move = model.predict_move(board) |
| print(move.uci()) # e.g. "e2e4" |
| ``` |
|
|
| ### MCTS Search (slower, stronger) |
| ```python |
| from mcts_engine import ParallaxChessMCTS |
| |
| engine = ParallaxChessMCTS("model.safetensors") |
| board = chess.Board() |
| move = engine.choose_move(board, n_simulations=200) |
| print(move.uci()) |
| ``` |
|
|
| ### Interactive GUI |
| ```bash |
| python play_gui.py |
| ``` |
| Click pieces to select, click again to move. Legal moves shown as dots. |
|
|
| ## Architecture |
|
|
| ``` |
| ParallaxChessV3( |
| board_encoder: Embedding(402, 512), |
| backbone: SmallLM(8 layers, 512 dim, 8 heads, GQA 4:2), |
| policy_head: Linear(512, 4352), # from_sq * 64 + to_sq |
| value_head: Linear(512, 256) → Linear(256, 1) → Tanh |
| ) |
| ``` |
|
|
| ## Training Details |
|
|
| 1. **Data**: 200K positions from Stockfish self-play (depth 10) + 143K Lichess puzzles |
| 2. **Policy target**: Stockfish best move as move index (from_square × 64 + to_square) |
| 3. **Value target**: Stockfish centipawn evaluation (scaled to [-1, 1]) |
| 4. **Optimizer**: AdamW (lr=1e-3, weight_decay=0.01, cosine schedule) |
| 5. **Augmentation**: 50% horizontal board flip |
| |
| ## What This Proves |
| |
| - A 25.9M param model can learn real chess openings from scratch |
| - Policy + value heads can be trained simultaneously on a single GPU |
| - MCTS search can boost a weak neural player to competitive play |
| - Custom chess encoding (no tokenizer dependency) works well |
| |
| ## Limitations |
| |
| - ~1000-1500 ELO (intermediate club player) |
| - Weak in endgames (training data biased toward openings/middlegame) |
| - No opening book — learns openings from training data only |
| - MCTS adds ~10x latency per move |
| |
| ## License |
| |
| CC BY-NC 4.0 (weights), AGPL-3.0 (code) |
| |
