NowChessSystems/modules/bot/README_WINDOWS.md

Windows Users: Start Here!

This guide gets you running the NNUE pipeline on Windows in 5 minutes.

TL;DR — Quick Start

1. Install prerequisites:

   pip install -r python/requirements.txt
   

2. Download Stockfish from https://stockfishchess.org/download/ and note the path

3. Run the pipeline:

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

Done! The pipeline will:

• Generate 500,000 chess positions (~2 min)
• Evaluate with Stockfish (~24-36 hours)
• Train neural network (~2-4 hours)
• Generate Scala code (~1 min)

Launcher Options

1. Command Prompt/PowerShell (Easiest)

cd modules\bot

REM Optional: set Stockfish path
set STOCKFISH_PATH=C:\stockfish\stockfish.exe

REM Run the pipeline
run_nnue_pipeline.bat

2. PowerShell (Colorful Output)

cd modules\bot

# Optional: set Stockfish path
$env:STOCKFISH_PATH = "C:\stockfish\stockfish.exe"

# Run the pipeline
.\run_nnue_pipeline.ps1

3. Git Bash (If You Have It)

cd modules/bot
export STOCKFISH_PATH=/c/stockfish/stockfish.exe
bash run_nnue_pipeline.sh

Available Scripts

Script	Location	Usage
run_nnue_pipeline.bat	modules/bot/	Windows batch launcher (easiest)
run_nnue_pipeline.ps1	modules/bot/	PowerShell launcher (colorful)
run_nnue_pipeline.sh	modules/bot/	Bash launcher (for Git Bash/WSL)
run_pipeline.bat	modules/bot/python/	Direct batch runner
run_pipeline.sh	modules/bot/python/	Direct bash runner

Step-by-Step Setup

Step 1: Check Python

python --version

If Python is not installed:

1. Download from https://python.org
2. Run installer
3. IMPORTANT: Check "Add Python to PATH"
4. Verify: python --version

Step 2: Install Dependencies

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

This installs:

• python-chess — chess engine interface
• torch — neural network training
• tqdm — progress bars

Step 3: Get Stockfish

Option A (Recommended): Download from https://stockfishchess.org/download/

• Extract to C:\stockfish
• Verify: C:\stockfish\stockfish.exe --version

Option B (If using Chocolatey):

choco install stockfish

Step 4: Run Pipeline

From modules\bot\:

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

What Each Step Does

Step 1: Generate Positions (2-3 minutes)

python python\generate_positions.py python\positions.txt

Creates 500,000 random chess positions saved to positions.txt

Step 2: Evaluate with Stockfish (24-36 hours)

set STOCKFISH_PATH=C:\stockfish\stockfish.exe
python python\label_positions.py python\positions.txt python\training_data.jsonl %STOCKFISH_PATH%

Evaluates each position at depth 12. This is the slowest step.

Step 3: Train Network (2-4 hours)

python python\train_nnue.py python\training_data.jsonl python\nnue_weights.pt

Trains a 768→256→32→1 neural network. Faster on GPU.

Step 4: Export Weights (1 minute)

python python\export_weights.py python\nnue_weights.pt src\main\scala\de\nowchess\bot\bots\nnue\NNUEWeights.scala

Exports PyTorch weights as Scala code.

Monitoring Progress

Check Step 2 (Stockfish) Progress

The Stockfish evaluation is slow but shows progress. Check the size of training_data.jsonl:

cd modules\bot\python
dir training_data.jsonl

The file grows as positions are evaluated. If it's increasing, the pipeline is working!

If Pipeline Gets Interrupted

The pipeline saves progress and can resume:

REM Just run the pipeline again
run_nnue_pipeline.bat

REM It will skip already-processed positions and continue

Troubleshooting

"python is not recognized"

Python isn't in PATH. Fix:

1. Reinstall Python from python.org
2. CHECK "Add Python to PATH" during installation
3. Restart Command Prompt

Or manually add to PATH:

1. Press Win+R, type systempropertiesadvanced.exe
2. Click "Environment Variables"
3. Add C:\Users\YourName\AppData\Local\Programs\Python\Python310 to Path

"stockfish not found"

Set the full path:

where stockfish
REM Then use the full path:
set STOCKFISH_PATH=C:\full\path\to\stockfish.exe

"ModuleNotFoundError: No module named 'torch'"

Reinstall PyTorch:

pip install torch==2.1.2

"CUDA out of memory"

If using GPU and training fails, reduce batch size:

Edit modules\bot\python\train_nnue.py, line ~91:

# Change from:
train_loader = DataLoader(train_dataset, batch_size=4096, shuffle=True)

# To:
train_loader = DataLoader(train_dataset, batch_size=2048, shuffle=True)

After Pipeline Completes

1. New file created: modules\bot\src\main\scala\de\nowchess\bot\bots\nnue\NNUEWeights.scala

2. Rebuild the project:

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

Expected Output

When running run_nnue_pipeline.bat, you should see:

=== NNUE Training Pipeline ===

Step 1: Generating 500,000 random positions...
[progress bar]
[OK] Positions generated

Step 2: Labeling positions with Stockfish (depth 12)...
[progress bar - this takes 24+ hours]
[OK] Positions labeled

Step 3: Training NNUE model (20 epochs)...
[progress bar showing epoch progress]
[OK] Model trained

Step 4: Exporting weights to Scala...
[progress bar]
[OK] Weights exported

=== Pipeline Complete ===

Next steps:
1. Navigate to project root: cd ..\..
2. Compile: .\compile.bat
3. Test: .\test.bat

Need More Info?

• Quick reference: See QUICKSTART.md
• Detailed setup: See WINDOWS_SETUP.md
• Complete docs: See python/README_NNUE.md
• Implementation details: See NNUE_IMPLEMENTATION_SUMMARY.md

Still Stuck?

Check WINDOWS_SETUP.md section "Troubleshooting" for more solutions, or see python/README_NNUE.md for common issues.