Running Leela Chess Zero in a Chess GUI
Leela Chess Zero (LCZero) utilizes the UCI (Universal Chess Interface) protocol, and hence can be run in any Chess GUI that supports that protocol. Engine-specific settings have to be provided via the command line, since the facility to do so via the GUI isn’t available yet.
Currently, the engine supports the following command line parameters:
| -h [ –help ] | Show command line options. |
| -t [ –threads ] arg | Number of threads to use, default = 2. |
| -p [ –playouts ] arg | Weaken engine by limiting the number of playouts. |
| -v [ –visits ] arg | Weaken engine by limiting the number of visits. |
| -n [ –noise ] | Before search begins, add Dirichlet noise to the root node policy’s move probabilities. |
| -m [–randomize] | After search is complete, select from the moves in proportion to their relative values (rather than ‘best only’). |
| -d [–tempdecay] arg | After search is complete, sometimes pick weaker moves for variety. Larger tempdecay values will do this less often, and the effect is reduced for moves later in the game. ‘0’ is equivalent to –randomize and results in more random moves. This is used by self-play games to explore new moves. ‘10’ is a reasonable value, and is used by test matches on the server for variety. |
| -s [ –seed ] arg | Random number generation seed. |
| -w [ –weights ] arg | File with network weights. |
| -l [ –logfile ] arg | File to log input/output to. |
| -q [ –quiet ] | Disable all diagnostic output. |
| –uci | Don’t initialize the engine until “isready” command is sent. Use this if your GUI is freezing on startup. |
| –start arg | Start command {train, bench}. |
| –supervise arg | Dump supervised learning data from the pgn. |
| –gpu arg | ID of the OpenCL device(s) to use (disables autodetection). |
| –full-tuner | Try harder to find an optimal OpenCL tuning. |
| –tune-only | Tune OpenCL only and then exit. |
| –puct arg | |
| –fpu_reduction arg | |
| –softmax_temp arg |
To run the engine in a Windows-based Chess GUI, the following files are required:
- lczero.exe*
- libopenblas.dll*
- libgcc_s_seh-1.dll (new with v0.6)*
- libgfortran-3.dll (new with v0.6)*
- libquadmath-0.dll (new with v0.6)*
- libwinpthread-1.dll (new with v0.6)*
- OpenCL.dll**
- leelaz_opencl_tuning (This file contains tuning parameters calculated for your GPU, and is created automatically on the first run of the training. It can also be created by manually running lczero.exe –tune-only or –full-tuner from the command line, see above. Please note that the initial creation of the file can take several minutes, because the tuning probes your hardware which takes time. Also note that this file is not required if you run the CPU-only version of LCZero.)
- The network file you want the engine to use* (Can be downloaded from here, has to be unpacked in order to be used; if taken from an existing local LCZero training instance, unpacking is not necessary, because the client already took care of that.)
*These files can either be downloaded from this site, or be taken from an existing local LCZero instance used to run the network training.
**This file might already exist on your machine (for example in %WINDIR%\SysWOW64), it’s being included in the package just in case it does not.
Note: If a file path that’s being fed to the engine contains spaces, you have to quote it. Example:
"C:/Program Files (x86)/Chess/Engines/LCZero/networks/id132"
Note: Utilization of Leela-chess in Fritz requires v0.6 (or higher) of the engine. Previous versions don’t work in Fritz.
In order to run Leela Chess Zero in Fritz, create a ‘LCZero’ subdirectory in Fritz’s installation folder, and copy the aforementioned required files to that folder. Alternatively, you can copy the Leela Chess Zero training instance folder to the aforementioned folder, since it contains the required files mentioned above. The network file for Leela Chess Zero should also reside in the aforementioned directory, and be named ‘weights.txt’ (this is so auto-detection of that file works).
Once you have the required files in place, add the engine to Fritz:
- In the Fritz start menu, click ‘Enter & Analyse’
- Select the ‘Engine’ tab, click ‘Create UCI Engine’
- In the ‘Set up UCI Engine’ dialog, select the ‘lczero.exe’ file located in the aforementioned folder via the respective file selection dialog
Name and Author should be filled in automatically, and no further configuration is required.
Fritz unfortunately doesn’t accept any command line parameters for external engines, so a little workaround is required to utilize the engine in this GUI. It is the utility ‘InBetween’ by Odd Gunnar Malin, which intercepts communication between the GUI and the engine, and allows on-the-fly modification of the transferred data. The utility can be downloaded here (scroll down). You use it as follows:
- Extract the files ‘InBetween.exe’ and ‘InBetween.ini’ to the aforementioned ‘LCZero’ subdirectory
- Edit ‘InBetween.ini’ and provide the following option in the [InBetween] section: CommandLine := lczero.exe –uci (optional: additional parameters according to the list above, for example –noponder; don’t forget to remove
;at the beginning of the line to activate the command)
Example:
CommandLine := lczero.exe --uci --noponder
- Save & Close the file
Once you have the required files in place, add the engine to Fritz:
- In the Fritz start menu, click ‘Enter & Analyse’
- Select the ‘Engine’ tab, click ‘Create UCI Engine’
- In the ‘Set up UCI Engine’ dialog, select the ‘InBetween.exe’ file located in the aforementioned folder via the respective file selection dialog
Name and Author should be filled in automatically, and no further configuration is required.
Note: For the purpose of creating this guide, v1.3 of the ‘InBetween’ utility has been used.
To finalize and verify the process, click ‘Ok’, then click ‘Change Main Engine’ and select LCZero from the list. Now start a new game by selecting ‘Home’ > ‘New Game’, and make the first move. LCZero should begin to play once it is her turn to do so.
In order to run Leela Chess Zero in Arena, create a ‘LCZero’ subdirectory in Arena’s ‘Engines’ folder, and copy the aforementioned required files to that folder. Alternatively, you can copy the Leela Chess Zero training instance folder to the ‘Engines’ folder, since it contains the required files mentioned above.
Once you have the required files in place, add the engine to Arena:
- In Arena, press <F11>
- Select ‘Details’, click ‘Installation wizard’
- Click ‘Forward >>’, and in the next dialog make sure Arena’s ‘Engines’ folder is selected
- Click ‘Forward >>’ again, then select the lczero.exe you’ve installed earlier from the list
- Click ‘Forward >>’ twice, then in the last dialog select ‘UCI’ and click ‘Forward >>’ one more time
The engine you just added should now be selected in ‘Details’. Now add the following configuration information:
- Name: LCZero <version/build> <network id/name>
- Author: Linscott, Huizinga, Olsen, Diamond et al.
- Command Line Parameters: -w <file_path_to_network_file> (optional: additional parameters according to the list above, for example –noponder)
- Country: Europe
- Type: UCI
- (Optional) Logo file: If you want the engine to use a logo file, you can download and use this one:
and in tab ‘Special:
- Website of the author: http://lczero.org
To finalize and verify the process, click ‘Apply’, then click ‘Start this engine right now!’. LCZero should be started, and by pressing <F4> you can verify her output in the engine log.
In order to run Leela Chess Zero in the GUI version of Cute Chess, create a ‘LCZero’ subdirectory in Cute Chess’ engines folder, and copy the aforementioned required files to that folder. Alternatively, you can copy the Leela Chess Zero training instance folder to the engines folder, since it contains the required files mentioned above.
Once you have the required files in place, add the engine to Cute Chess:
- In Cute Chess, select ‘Tools’ > ‘Settings’, then click the ‘Engines’ tab
- Click the ‘+’ in the lower left corner of that tab to open the ‘Add engine’ dialog
Now add the following configuration information:
- Name: LCZero <version/build> <network id/name>
- Command: lczero.exe -w <file_path_to_network_file> (optional: additional parameters according to the list above, for example –noponder)
- Working Directory: <file_path_to_LCZero_folder>
- Protocol: uci
To finalize and verify the process, click ‘Ok’, close the ‘Settings’ dialog, then select ‘Game’ > ‘New…’, and assign the engine to either White or Black by selecting ‘CPU’ and choosing LCZero from the list of engines. Click ‘Ok’ to start the game. LCZero should be loaded and begin to play once it is her turn to do so.
In order to run Leela Chess Zero in Scid vs. PC, create a ‘LCZero’ subdirectory in Scid vs. PC’s ‘bin\engines’ folder, and copy the aforementioned required files to that folder. Alternatively, you can copy the Leela Chess Zero training instance folder to the ‘bin\engines’ folder, since it contains the required files mentioned above.
Once you have the required files in place, add the engine to Scid vs. PC:
- In Scid vs. PC, select ‘Tools’ > ‘Analysis Engines’ to open the ‘Analysis Engines’ dialog
- Click ‘New’ to open the ‘Configure Engine’ dialog
Now add the following configuration information:
- Name: LCZero <version/build> <network id/name>
- Command: <file_path_to_LCZero_folder>/bin/engines/LCZero/lczero.exe
- Directory: <file_path_to_LCZero_folder>
- Parameters: -w <file_path_to_network_file> (optional: additional parameters according to the list above, for example –noponder)
- Webpage: http://lczero.org
- Protocol: UCI
To finalize and verify the process, click ‘Ok’, then click ‘Start’, and close the ‘Analysis Engines’ dialog. The engine should immediately start, and begin to analyze. To verify gameplay, select ‘Play’ > ‘Tournament’, and assign the engine to one of the two engine slots (assign a different one to the other slot), then click ‘Ok’ to start the tournament. Both engines should be loaded and begin to play.
Note: All file paths configured in Scid vs. PC require a slash (/) as file path separator, not a backslash (\).
In order to run Leela Chess Zero in Lucas Chess, create a ‘LCZero’ subdirectory in Lucas Chess’s ‘Engines\Windows’ folder, and copy the aforementioned required files to that folder. Alternatively, you can copy the Leela Chess Zero training instance folder to the ‘Engines\Windows’ folder, since it contains the required files mentioned above.
The network file for Leela Chess Zero should also reside in the aforementioned directory, and be named ‘weights.txt’ (this is so auto-detection of that file works).
Once you have the required files in place, add the engine to Lucas Chess:
- In Lucas Chess, select ‘Extras’ > ‘Engines’ > ‘External Engines’ to open the ‘External Engines’ dialog
- Click ‘Command’, select the ‘lczero.exe’ file, and in the ‘Argument 1’ field, enter the following argument: –uci (if you want to enter more arguments, enter them in the following ‘Argument x’ fields, one argument per field)
- Click ‘Accept’ to close the dialog. The engine is being detected, and its configuration dialog will open.
Now enter the configuration options as desired (UCI options are also configured here).
Lucas Chess unfortunately doesn’t recognize Leela Chess Zero (lczero.exe) as an UCI engine, so a little workaround is required to utilize the engine in this GUI. It is the utility ‘InBetween’ by Odd Gunnar Malin, which intercepts communication between the GUI and the engine, and allows on-the-fly modification of the transferred data. The utility can be downloaded here (scroll down). You use it as follows:
- Extract the files ‘InBetween.exe’ and ‘InBetween.ini’ to the aforementioned ‘LCZero’ subdirectory
- Edit ‘InBetween.ini’ and provide the following option: CommandLine := lczero.exe -w <file_path_to_network_file> (optional: additional parameters according to the list above, for example –noponder; don’t forget to remove
;at the beginning of the line to activate the command)
Example:
CommandLine := lczero.exe -w networks/id124 --noponder
- Save & Close the file
Once you have the required files in place, add the engine to Lucas Chess:
- In Lucas Chess, select ‘Extras’ > ‘Engines’ > ‘External Engines’ to open the ‘External Engines’ dialog
- Click ‘Command’, select the ‘InBetween.exe’ file, then click ‘Accept’, which will open the engine configuration dialog
Now add the following configuration information:
- Name: LCZero <version/build> <network id/name>
Note: For the purpose of creating this guide, v1.3 of the ‘InBetween’ utility has been used.
To finalize and verify the process, click ‘Accept’; the engine should now show up in the ‘External Engines’ list. Close the ‘External Engines’ dialog. To verify gameplay, select ‘Play’ > ‘Play against an engine of your choice’, and assign the engine as your opponent in the ‘Basic configuration’ tab. Click ‘Accept’ to close the dialog. The game will begin immediately, and LCZero will make the first move.