✦ Soul

Soul is a modern, hand-crafted evaluation (HCE) alpha-beta chess engine written in Rust.

Rather than relying on black-box Neural Networks, Soul pushes traditional algorithmic evaluation to its absolute limit with SIMD acceleration, zero-cost abstractions, and a custom tuning framework built from scratch.

It supports the UCI and XBoard protocols, plus full Chess960 (Fischer Random).

Quick Start

You will need rustup with the nightly toolchain and make. The pinned nightly version is specified in rust-toolchain.toml and will be installed automatically by rustup on first build.

Warning

Due to heavy SIMD optimization inside the evaluation accumulator, Soul strictly requires an AVX2 capable CPU (x86-64-v3 architecture or newer). Older CPUs are not supported.

Building

make pgo     # Profile-Guided Optimization (Recommended)

make native  # Optimized specifically for your host CPU
make v4      # AVX512
make v3      # AVX2, BMI2

Development

make debug   # Debug build
make test    # Run test suite
make clippy  # Lint with clippy
make format  # Format with rustfmt

Tuning & Datasets

Soul uses a custom binary format (.soul.zst) for faster bulk I/O during tuning.

Generating Data

Generate self-play data for evaluation tuning:

./soul genfens -t <N> -n <N>

You can inspect datasets or encode existing EPDs using the built-in dataset utilities (./soul dataset help).

Evaluation Tuning

Tune the hand-crafted evaluation parameters using the Lion optimizer:

make evaltune
./eval --dataset data/data.soul.zst --epochs 4000

Search Tuning

Tune search parameters (like pruning margins and MVV-LVA bias) using Soft Active CMA-ES:

make searchtune
./search --openings book.epd --epochs 100 --tc "4+0.04"

(Results auto-save to searchtune_checkpoint.json and can be resumed with --resume.)

🎮 Configuration (UCI / XBoard Options)

Soul exposes the following options via both protocols:

Option	Default	Description
Hash	16	Transposition Table size in MB (reserved; TT not yet implemented)
Threads	1	Number of search threads
Overhead	10	Move time overhead buffer in ms
UCI_ShowCurrMove	true	Show current move being searched
UCI_ShowWDL	false	Show Win/Draw/Loss estimates (uses Stockfish coefficients; inaccurate on Soul's scale)
UCI_Chess960	false	Enable Fischer Random Chess mode

⚖️ License

AGPL-3.0 – See LICENSE for details.

TL;DR:

Permissions:

• ✓ Free to use, study, and modify
• ✓ Can distribute original or modified versions
• ✓ Commercial use allowed

Conditions:

• Must provide source code to users who access it over a network
• Derivative works must be licensed under AGPL-3.0
• Changes must be documented
• Must include original copyright and license notice

Limitations:

• ✗ No warranty
• ✗ No liability

In no particular order, Special Thanks

Lofty – The author of Yukari, for being a patient and understanding friend. Also helped me understand Xboard.
Lily – The author of Rose and co-author of Clockwork, for always getting me. Check her ByteBoard Attack Tables blog!
Cosmo – The author of Viridithas, for being a cool dude and helping me start with The Rust Programming Language.
Jonathan Hallström – The author of Pawnocchio, for being a great cheering friend and motivating me not to give up.
Styx – The co-author of Reckless, for being a great friend and helping minimize my loss of sanity.