NowChessSystems/modules/bot/QUICKSTART.md

NNUE Pipeline Quickstart

Prerequisites

Install Python Dependencies

cd modules/bot/python
pip install -r requirements.txt

Install Stockfish

macOS:

brew install stockfish

Linux (Debian/Ubuntu):

apt-get install stockfish

Windows:

• Download from https://stockfishchess.org
• Or use Chocolatey: choco install stockfish
• Add to PATH or set STOCKFISH_PATH environment variable

Run the Full Pipeline

Easiest: Launcher Scripts (Recommended)

From modules/bot/ directory:

Windows (Command Prompt or PowerShell):

run_nnue_pipeline.bat

Linux/macOS/Windows (Git Bash/WSL):

chmod +x run_nnue_pipeline.sh
./run_nnue_pipeline.sh

Alternative: Direct Scripts

From modules/bot/python/ directory:

Windows (Command Prompt):

cd python
set STOCKFISH_PATH=C:\path\to\stockfish.exe
run_pipeline.bat

Bash (Linux, macOS, Git Bash, WSL):

cd python
export STOCKFISH_PATH=/path/to/stockfish
chmod +x run_pipeline.sh
./run_pipeline.sh

PowerShell (Windows):

cd python
$env:STOCKFISH_PATH = "C:\path\to\stockfish.exe"
bash ./run_pipeline.sh

The pipeline will:

1. Generate 500,000 random positions (~2-3 minutes)
2. Evaluate with Stockfish depth 12 (~24-36 hours on typical machine)
3. Train NNUE network (20 epochs, ~2-4 hours on GPU)
4. Export weights to Scala (~1 minute)

For Quick Testing

Reduce the position count to test the pipeline quickly:

# Edit generate_positions.py, change:
# for game_num in range(500000):  # Change 500000 to 1000
# for game_num in range(1000):

Then run:

./run_pipeline.sh

This will complete in ~30-60 minutes total, allowing you to test the full pipeline.

After Pipeline Completes

# Navigate to project root
cd ../..

# Recompile (loads the new NNUEWeights.scala)
./compile

# Run tests
./test

Architecture Quick Reference

• Input: Board position (768 binary features)
• Network: Linear(768→256) → ReLU → Linear(256→32) → ReLU → Linear(32→1)
• Output: Centipawn evaluation (-20000 to +20000)
• Training: Stockfish evals → sigmoid(eval/400) targets → MSE loss

Troubleshooting

"Module not found: chess"

pip install python-chess==1.10.0

"CUDA out of memory"

• Edit train_nnue.py line 91: change batch_size=4096 to batch_size=2048

"Stockfish not found"

export STOCKFISH_PATH=$(which stockfish)
# or provide full path
export STOCKFISH_PATH=/usr/bin/stockfish

"ModuleNotFoundError: No module named 'torch'"

pip install torch==2.1.2

Files Generated

• positions.txt — 500,000 FENs
• training_data.jsonl — FEN + Stockfish evaluation pairs
• nnue_weights.pt — PyTorch model
• ../src/main/scala/de/nowchess/bot/bots/nnue/NNUEWeights.scala — Scala code

See README_NNUE.md for detailed documentation.