README.md

---
license: mit
language: en
inference: false
library_name: generic
tags:
  - chess
  - alphazero
  - stockfish
  - knowledge-distillation
  - pytorch
  - neural-chess-engine
base_model: []
---

# ChessModel-XPU — `formal_1m` checkpoint

A compact policy / WDL residual network for chess, trained by distilling
**Stockfish 18** MultiPV / WDL analysis. This is the `formal_1m` checkpoint from
the [ChessModel-XPU](https://github.com/JinShuo-Li/ChessModel) project — the
`main_xpu` / `main_cuda` preset (12 residual blocks × 192 channels, **8,932,076
parameters**, squeeze-and-excitation with hidden 32).

It is intended to be used together with chess rules and batched PUCT search as a
neural chess engine. The network alone does **not** play chess; the playable engine
runs MCTS-style PUCT over it. See the source repository for the search code.

> Research artifact. The project optimizes for *strength per unit compute*, not
> absolute strength, and makes **no Elo claim** for this checkpoint. Measured
> strength is reported through the project's paired Stockfish evaluation matches,
> not asserted here.

## Model details

| | |
|---|---|
| Architecture | BatchNorm residual tower, spatial 73-plane policy head, 3-logit Win/Draw/Loss head (no moves-left head in this checkpoint) |
| Preset | `main_xpu` (`main_cuda` on the Linux/CUDA branch) — 12 blocks × 192 channels, SE hidden 32 |
| Parameters | 8,932,076 |
| Input | `112 × 8 × 8` planes, canonically oriented to the side to move (8 history frames, castling rights, en-passant, side to move, halfmove/fullmove clocks) |
| Policy output | AlphaZero `8×8×73 = 4672` move encoding (56 queen rays, 8 knight moves, 9 underpromotions); illegal logits are masked |
| Value output | 3 logits → Win / Draw / Loss |
| License | MIT (see [LICENSE](https://github.com/JinShuo-Li/ChessModel/blob/main/LICENSE)) |
| Developer | JinShuo-Li |

## Training

Distilled from Stockfish 18 teacher labels; trained on the companion dataset
[`jinshuoli/chessmodel-data`](https://huggingface.co/datasets/jinshuoli/chessmodel-data).

Key settings from `configs/formal_1m.yaml`:

| | |
|---|---|
| Batch size | 512 |
| Epochs | 20 |
| Learning rate | 1e-3, cosine schedule, 2000 warmup steps |
| Weight decay | 1e-4 |
| Loss | policy 1.0 + value 1.0 (Win/Draw/Loss) |
| Precision | BF16 autocast |
| Teacher | Stockfish 18, MultiPV 8, 10000 nodes/position, WDL enabled, temperature 0.15 |

## Files

| Path | Description |
|---|---|
| `checkpoints/formal_1m_latest.pt` | Torch checkpoint. Stores `architecture` (model kwargs), `model` (state_dict), optimizer/scheduler state, `global_step`, `epoch`, and the training `config`. |

## How to load

The checkpoint is a project-specific `state_dict`; you need the project's model
code. Clone the repo and download the checkpoint so the path resolves unchanged:

```bash
git clone https://github.com/JinShuo-Li/ChessModel.git
cd ChessModel
hf download jinshuoli/chessmodel checkpoints/formal_1m_latest.pt --local-dir .
```

Load the weights:

```python
import torch
from chess_ai.model import ChessNetwork
from chess_ai.training.checkpoint import load_checkpoint

state = torch.load("checkpoints/formal_1m_latest.pt", map_location="cpu", weights_only=False)
model = ChessNetwork(**state["architecture"])          # 12×192, SE hidden 32
load_checkpoint("checkpoints/formal_1m_latest.pt", model)
model.eval()
```

Run it as an engine / evaluate it through the project's CLI:

```bash
# UCI-style play (batched PUCT search)
python play.py --checkpoint checkpoints/formal_1m_latest.pt --device cuda --simulations 800

# Neural metrics on teacher shards
python evaluate.py --checkpoint checkpoints/formal_1m_latest.pt \
    --dataset data/formal_50k_validation --device cuda
```

## Intended use and limitations

- **Intended:** chess-engine and reinforcement-learning research, distillation
  experiments, reproducibility of the project's results.
- **Not a ready-to-use HF model:** it cannot be run through the standard Inference
  API or `transformers`; it requires the project's search/engine code.
- **Strength:** deliberately modest — this is a compact research model, not a
  competitive engine. Do not treat it as a strong chess player.

## Related

- Dataset: [`jinshuoli/chessmodel-data`](https://huggingface.co/datasets/jinshuoli/chessmodel-data)
- Source code & documentation: [github.com/JinShuo-Li/ChessModel](https://github.com/JinShuo-Li/ChessModel)