philipchess

philipchess is an AlphaZero-style chess engine written in C++ and Python. It relies on a deep neural network to evaluate positions and guide Monte Carlo Tree Search (MCTS), trained entirely via self-play reinforcement learning.

The engine utilizes a centralized ZeroMQ inference server. The server batches neural network evaluations on the GPU, allowing multiple independent MCTS worker processes (such as UCI interfaces, self-play generators, or web handlers) to search concurrently with high throughput.

The final trained model operates at an estimated strength of ~1950 Elo and solves advanced tactics (2000-3000 Elo rating) with roughly 63% accuracy at 4000 MCTS iterations. Full training metrics and benchmarks can be found in the results/ directory.

Results & Benchmarks

The model was trained iteratively, scaling from a 1M to 5M position replay buffer. Its progression was evaluated against Lichess puzzle datasets and the Stockfish engine.

Training Progression	Tactical Accuracy (800 MCTS)
Compute Scaling (Test-Time)	Stockfish 5+0.1 Gauntlet

• Compute Scaling: Giving the final network more time to "think" (4000 MCTS vs 100 MCTS) yields a significant +17% absolute accuracy gain on advanced master-level puzzles without changing the network weights.
• Elo Estimate: Over an 800-game gauntlet at blitz time controls (5+0.1), the engine achieved a 50% parity threshold at exactly ~1956 Elo.

Prerequisites & Installation

This project is built and tested on Linux (Ubuntu/Debian). It requires Python 3, a C++20 compatible compiler, CMake, and an NVIDIA GPU (RTX 20-series or newer) for viable inference speeds.

1. System Dependencies

Install the required system packages, including the ZeroMQ C++ libraries required for the inference server:

sudo apt-get update
sudo apt-get install -y build-essential cmake git wget unzip libzmq3-dev

2. Python Environment

Create a virtual environment and install the required dependencies:

python3 -m venv env
source env/bin/activate
pip install -r requirements.txt

3. LibTorch (C++ PyTorch API)

Download and extract the CUDA 12.1 version of LibTorch into the project root:

wget https://download.pytorch.org/libtorch/cu121/libtorch-cxx11-abi-shared-with-deps-2.3.0%2Bcu121.zip
unzip -q libtorch-cxx11-abi-shared-with-deps-2.3.0+cu121.zip
rm libtorch-cxx11-abi-shared-with-deps-2.3.0+cu121.zip

4. Build the C++ Binaries

Use CMake to build the inference server and search engines:

mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH=$(pwd)/../libtorch -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)
cd ..

5. Download the Pre-Trained Model

Download the final trained weights (~14MB) from the GitHub Releases page and place the file in the models directory:

mkdir -p models
wget -O models/philipchess_model_latest.pt https://github.com/philipfabianek/philipchess/releases/download/v1.0/philipchess_model_latest.pt

Running the Engine

Because the architecture separates neural network inference from search, the inference server must be running before evaluating, training, or playing.

Start the inference server from the root directory:

./build/philipchess_server --model models/philipchess_model_latest.pt

Web Interface

To play against the engine via a browser, leave the server running and start the Flask application in a new terminal:

cd web
python app.py

Navigate to http://127.0.0.1:5000 in your browser.

Dataset Generation (Lichess Puzzles)

To evaluate the engine's tactical vision, we extract and filter specific puzzle sets from the open-source Lichess puzzle database based on Elo constraints and tactical motifs.

You can generate your own custom test suites using the unified data script:

# Generate 500 beginner puzzles (≤1200 Elo)
python scripts/generate_tactics.py --difficulty beginner --num 500

# Generate 1000 advanced puzzles (2000-3000 Elo)
python scripts/generate_tactics.py --difficulty advanced --num 1000

Evaluation (Puzzle Gauntlets)

You can benchmark specific checkpoints against tactical puzzle sets. The evaluation script automatically spins up a temporary backend server on specified ports.

Run the evaluation script from the project root:

python scripts/evaluate.py \
  --mode specific \
  --model models/philipchess_model_latest.pt \
  --test-port 7771 --data-port 7772 \
  --suite data/tactics_beginner.csv \
  --mcts 800

Playing against Stockfish (Fastchess Gauntlet)

To establish an Elo rating, the engine interfaces with standard chess GUIs and tournament managers via the UCI protocol.

1. Install Fastchess and Dependencies

This installs Stockfish and compiles a clean Fastchess binary into the eval/ directory:

sudo apt-get update
sudo apt-get install -y stockfish

cd eval
git clone https://github.com/Disservin/fastchess.git fastchess_src
make -j -C fastchess_src
mv fastchess_src/fastchess .
rm -rf fastchess_src
cd ..

2. Run the Tournament

Ensure your main philipchess_server is running in the background. Execute the gauntlet from the root directory using the UCI adapter wrapper.

Note: Because philipchess is configured to evaluate a fixed 800 MCTS iterations per move in the UCI wrapper, it is given a dummy time control of 1 hour (3600+0) to prevent GUI timeouts, while Stockfish plays at a standard blitz time control (5+0.1).

./eval/fastchess \
  -engine dir=. cmd=scripts/uci_adapter.py name=PhilipChess tc=3600+0 \
  -engine cmd=stockfish name=Stockfish_2000 option.UCI_LimitStrength=true option.UCI_Elo=2000 tc=5+0.1 \
  -rounds 50 -games 2 -concurrency 16 \
  -openings file=eval/openings.epd format=epd order=random plies=16

Training

To resume or start new self-play generation, start the central server, then execute the worker node binary. The worker node will prompt you to select the distributed training mode:

./build/philipchess_trainer

Workers will automatically begin generating games and pushing serialized tensors via ZeroMQ to the central server, which continuously trains the network and exports new checkpoints.