---
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)