NowChessSystems/modules/bot/WINDOWS_INDEX.md

Windows NNUE Pipeline — Complete Guide

Quick Links

Start here: README_WINDOWS.md — 5-minute quick start

Documentation Files

File	Purpose	Time to Read
README_WINDOWS.md	Windows quick start guide	5 min
WINDOWS_SETUP.md	Detailed Windows setup with troubleshooting	10 min
QUICKSTART.md	Cross-platform quick reference	5 min
python/README_NNUE.md	Complete pipeline documentation	15 min
NNUE_IMPLEMENTATION_SUMMARY.md	Technical implementation details	10 min

Launcher Scripts

All scripts work from modules\bot\ directory.

Windows Command Prompt / PowerShell

set STOCKFISH_PATH=C:\path\to\stockfish.exe
run_nnue_pipeline.bat

PowerShell (Colorful, Recommended)

$env:STOCKFISH_PATH = "C:\path\to\stockfish.exe"
.\run_nnue_pipeline.ps1

Git Bash / WSL

export STOCKFISH_PATH=/c/path/to/stockfish.exe
bash run_nnue_pipeline.sh

Python Pipeline Scripts

Located in modules\bot\python\:

Script	Purpose
generate_positions.py	Step 1: Generate 500K random positions
label_positions.py	Step 2: Evaluate with Stockfish
train_nnue.py	Step 3: Train neural network
export_weights.py	Step 4: Export to Scala
run_pipeline.bat	Windows batch runner
run_pipeline.sh	Bash runner

Getting Started (3 Steps)

1. Install Python

REM Check if Python is installed
python --version

REM If not, download from https://python.org
REM During installation, CHECK "Add Python to PATH"

2. Install Dependencies

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

3. Get Stockfish

• Download from https://stockfishchess.org/download/
• Extract to C:\stockfish
• Verify: C:\stockfish\stockfish.exe --version

4. Run Pipeline

cd modules\bot
set STOCKFISH_PATH=C:\stockfish\stockfish.exe
run_nnue_pipeline.bat

FAQ

How long does it take?

• Step 1 (positions): 2-3 minutes
• Step 2 (Stockfish): 24-36 hours ← slowest
• Step 3 (training): 2-4 hours (faster with GPU)
• Step 4 (export): 1 minute
• Total: 26-40 hours

Can I pause and resume?

Yes! The pipeline saves progress:

1. Press Ctrl+C to stop
2. Run the pipeline again - it will resume where it left off

Does it use my GPU?

Yes, automatically! If you have NVIDIA GPU:

• Training will be 5-10x faster
• Requires CUDA Toolkit (optional, not required)

Can I test with fewer positions?

Yes! Edit python\generate_positions.py:

# Change line 9 from:
for game_num in range(500000):

# To:
for game_num in range(10000):

This will complete in ~30 minutes instead of 26+ hours.

File Locations After Pipeline

modules\bot\
├── python\
│   ├── positions.txt                    (15 MB - raw positions)
│   ├── training_data.jsonl              (100 MB - FEN + eval)
│   ├── nnue_weights.pt                  (3 MB - trained weights)
│   └── [python scripts]
├── src\main\scala\de\nowchess\bot\bots\nnue\
│   ├── NNUEWeights.scala                (10 MB - generated weights)
│   ├── NNUE.scala                       (inference engine)
│   ├── EvaluationNNUE.scala             (weights trait)
│   └── NNUEBot.scala                    (bot implementation)
└── [launcher scripts]

Environment Variables

Set these before running the pipeline:

REM Required (unless Stockfish is in PATH)
set STOCKFISH_PATH=C:\stockfish\stockfish.exe

REM Optional: specify Python version
set PYTHON_CMD=python3

Or in PowerShell:

$env:STOCKFISH_PATH = "C:\stockfish\stockfish.exe"
$env:PYTHON_CMD = "python3"

Troubleshooting Flow

1. Python not found → Install from python.org, check "Add to PATH"
2. Stockfish not found → Download from stockfishchess.org, set STOCKFISH_PATH
3. Module not found → Run pip install -r requirements.txt
4. GPU out of memory → Reduce batch size in train_nnue.py
5. Pipeline hangs → Check training_data.jsonl size, Stockfish evaluation is slow

See WINDOWS_SETUP.md for detailed troubleshooting.

Next Steps After Pipeline

1. Verify output:

   cd ..\..\
   compile.bat
   test.bat
   

2. Use NNUEBot in your engine:

   val bot = new NNUEBot(difficulty, rules, book)
   val move = bot.nextMove(context)
   

Support

• Quick help: README_WINDOWS.md
• Detailed help: WINDOWS_SETUP.md
• Technical details: NNUE_IMPLEMENTATION_SUMMARY.md
• Complete reference: python/README_NNUE.md

---

Platform: Windows 10/11 (tested on Windows 11)
Requirements: Python 3.8+, Stockfish 14+
Languages: Python, Scala 3
Status: ✅ Production Ready