The **Cerebrum library** can be used to train and utilize "[NNUE](https://www.chessprogramming.org/NNUE)-like" neural networks for chess engines. It was initially designed and created for the [Orion UCI chess engine](https://www.orionchess.com/).

- **Training now relies on game results** (from which a win ratio is deduced for each position during a game) and **material only** !

- **Data preparation** scripts are provided to automate the preparation of training data (using one or several pgn files)

- **Network quantization** is performed at the end of each training epoch, allowing the choice between better accuracy or increased inference speed

- A **basic UCI chess engine** is provided in two versions (standard or quantized) to demonstrate how to load and use the network

- Inference C code is now also available in two versions (standard or quantized)

<br/>

The library consists of four main parts:

1. **Data preparation code** (Python scripts)

2. **Training code** (Python script)

3. **Inference code** (C files)

4. A **basic UCI chess engine** for demonstration purposes (Python script)

<br/>

To use the library, you will first need to:

- Download the `v1.0` folder of this repository

- Install a Python runtime: https://www.python.org/

- Install some Python librairies: `pip install torch numpy scipy tqdm chess`

- Download the [pgn-extract](https://www.cs.kent.ac.uk/people/staff/djb/pgn-extract/) tool and put the `pgn-extract.exe` file in the folder `./1. data preparation/`

<br/>

Note that, **by default, training is forced to use the CPU**. If you have an NVIDIA GPU, you can:

- Install the appropriate version of the torch library (see links below) to improve training speed

- Set `FORCE_CPU_DEVICE` to `False` in the script `train.py` (line 53) to enable GPU usage

<br/>

You can choose to provide one or several pgn files containing full games in the folder `./1. data preparation/pgn/`.

Then launch the script `prepare.bat` in the folder `./1. data preparation/` to obtain a file named `positions-shuffled.txt` which will be stored in the same folder.

This script will parse games and compute the average win ratio for each encountered position in all the games. It will also add some other statistical information (popcount, number of occurences of each position).

Copy the `positions-shuffled.txt` file to the folder `./2. training/positions/`

Note that, **by default, all games after 31.12.2023 will be ignored**. You can easily modify this by editing the script `prepare.bat` (see source to discover how).

<br/>

Prepare your own handcrafted file containing position (fenstring), side to move, popcount, number of occurences of this position, win ratio:

<br/>

This alternative can be useful when you already have a good idea of the win ratio associated to a (large) bunch of positions.

The provided file must be called `positions-shuffled.txt` and be placed in the folder `./2. training/positions/`.

<br/>

Launch the script `train.bat` in the folder `./2. training/`.

This script will parse the `positions-shuffled.txt` file in the folder `./2. training/positions/`, split it in batches of training data (this step can be long), and then use these data to train the neural network.

<br/>

Trained networks will be located in the folder `./2. training/networks/`. One network will be saved at the end of each training epoch.

By default:

- `epoch-5.txt` will be the last standard network (i.e. full precision: weights and biases are stored as `float`)

- `epoch-5-q.txt` will be the last quantized network (i.e. less precision, but high inference speed: weights and biases are stored as `int8`)

<br/>

These networks can now be used in your own engine, using your own code, or:

- using the provided inference C code in `./3. inference/1. standard/` or `./3. inference/2. quantized/` folders

- using the provided inference Python code located in the `./4. engine/1. standard/` or `./4. engine/2. quantized/` folders

<br/>

In order to use your own trained network with the provided Cerebrum UCI chess engine:

- Copy the `epoch-5.txt` (resp. the `epoch-5-q.txt`) file in the folder `4. engine/1. standard/` (resp. `4. engine/2. quantized/`

- Rename it to `network.txt`

- Launch the engine

<br/>

In order to use your own trained network with Orion UCI chess engine (assuming you did not change the network architecture):

- Install a copy of Orion in a distinct folder of the regular Orion

- Remove any `orion64-v1.0.nn` or `network.txt` existing file in that folder

- Copy the `epoch-5-q.txt` file in the folder

- Rename it to `network.txt`

- Launch the copy of Orion: Orion will not find any `orion64-v1.0.nn` file, but will find a `network.txt` file, and then will convert it to a new `orion64-v1.0.nn` file

- Rename `orion64-v1.0.nn` as you want

Note: this is not super user-friendly, and will be enhanced in a next version ;-)

<br/>

You can adjust the name and author of the trained networks:

- Before training, by modifying the `NN_NAME` (default = "Orion 1.0") and `NN_AUTHOR` (default = "David Carteau") variables in the script `train.py` located in the folder `./2. training/` (see lines 59 and 60)

- After training, by modifying the first two lines of the generated networks (default = "name=Orion 1.0" and "author=David Carteau")

<br/>

If you want to obtain the exact same neural network used in Orion 1.0, additional steps are required:

- Download the [3, 4, 5 pieces](http://tablebase.sesse.net/syzygy/3-4-5/) endgame **Syzygy tablebases** and put them in the folder `./1. data preparation/syzygy/3-4-5/`

- Download the [6 pieces](http://tablebase.sesse.net/syzygy/6-WDL/) endgame Syzygy tablebases and put them in the folder `./1. data preparation/syzygy/6-pieces/`

- Download [CCRL 40/4 archive](https://computerchess.org.uk/ccrl/402.archive/games.html) + [CCRL BLITZ](https://computerchess.org.uk/ccrl/404/games.html) + [CCRL 40/15](https://computerchess.org.uk/ccrl/4040/games.html) games, unzip the 3 files to the folder `./1. data preparation/pgn/`

<br/>

- `torch==2.1.2 --index-url https://download.pytorch.org/whl/cpu`

- or, if you have an **NVIDIA GPU** `torch==2.1.2 --index-url https://download.pytorch.org/whl/cu121`

- `numpy==1.26.3`

- `scipy==1.11.4`

- `tqdm==4.66.1`

- `chess==1.10.0`

Important: to obtain the exact same neural network, let the `FORCE_CPU_DEVICE` variable set to `True` in the script `train.py` (line 53).

<br/>

Feel free to adapt the library to meet your specific needs, and do not hesitate to provide feedback ! 🌟

<br/>