Introduction
------------
Texel is a free software (GPL v3) chess engine written in C++11.
More information about the program is available in the chess programming wiki:
https://www.chessprogramming.org/Texel
Pre-compiled executables
------------------------
The Texel distribution contains the following pre-compiled executables
located in the bin directory:
texel64-avx512.exe
For Windows 7 or later x86-64 systems using AVX-512, VNNI, POPCOUNT and BMI2
instructions.
texel64-avx2-bmi.exe:
For Windows 7 or later x86-64 systems using AVX2, POPCOUNT and BMI2
instructions.
texel64-avx2-pop.exe:
For Windows 7 or later x86-64 systems using AVX2 and POPCOUNT instructions.
texel64-avx2.exe:
For Windows 7 or later x86-64 systems using AVX2 instructions.
texel64-ssse3.exe
For Windows x86-64 systems with SSSE3 support.
texel64-old.exe
For Windows x86-64 systems.
texel64cl.exe:
Cluster version of texel64-avx2-pop.exe.
Requires Microsoft MPI to be installed.
texel-arm64:
For the ARMv8-A 64-bit architecture.
Should work on most modern Android devices.
texel-arm64-dot:
For the ARMv8-A 64-bit architecture with dot product CPU instruction.
Should work on many modern Android devices.
texel64:
For Linux x86-64 systems with AVX2 and POPCOUNT support.
If you need an executable for a different system, see the "Compiling" section
below.
UCI options
-----------
Hash
Controls the size of the main (transposition) hash table. Texel supports up to
512GiB for transposition tables. Other hash tables are also used by the
program, such as a pawn hash table. These secondary tables are quite small and
their sizes are not configurable.
OwnBook
When set to true, Texel uses its own opening book. When set to false,
Texel relies on the GUI to handle the opening book.
BookFile
If set to the file name of an existing polyglot opening book file, Texel uses
this book when OwnBook is set to true. If set to an empty string, Texel uses
its own small built in book when OwnBook is true. BookFile is not used when
OwnBook is false. An opening book called texelbook.bin is included in this
distribution.
Ponder
Texel supports pondering mode, also called permanent brain. In this mode the
engine calculates also when waiting for the other side to make a move. This
option changes the time allocation logic to better suit pondering mode. The
option is normally handled automatically by the GUI.
UCI_AnalyseMode
This option is normally set automatically by the GUI when in analysis mode.
In analysis mode, Texel does not use its opening book.
Strength
Strength can be smoothly adjusted between playing random legal moves (0) and
playing at full strength (1000).
UCI_LimitStrength, UCI_Elo
These are standard UCI options to reduce the playing strength and should be
handled by the GUI. Internally the Elo value is converted to a Strength value,
so the Strength option has no effect when UCI_LimitStrength is enabled.
MaxNPS
If set to a value larger than 0, Texel will not search faster than this many
nodes per second. This can be used as an alternative to or in combination with
the Strength option to reduce the playing strength.
Threads
Texel can use multiple CPUs and cores using threads. For best performance,
don't set this value higher than the number of cores or hyperthreads in the
computer.
MultiPV
Set to a value larger than 1 to find the N best moves when analyzing a
position. This setting has no effect when playing games. The GUI normally
handles this option so the user does not have to set it manually.
UseNullMove
When set to true, the null move search heuristic is disabled. This can be
beneficial when analyzing positions where zugzwang is an important factor.
Contempt
When playing a game this value specifies how big an advantage, measured in
centipawns, the engine thinks it has over its opponent, because of differences
in playing strengths. A positive value means the engine sees itself as
stronger than the opponent and therefore tries to avoid draws by repetition
and simplifying piece trades. A negative value has the opposite effect,
causing the engine to actively look for draws and simplifying exchanges.
AnalyzeContempt
When analyzing a position the AnalyzeContempt value is used instead of the
Contempt value. AnalyzeContempt is always specified from the white player's
point of view, even when it is black's turn to move. For example, if you are
analyzing an adjourned game where you are playing white and are happy with a
draw, you can set AnalyzeContempt to a negative value, such as -50. The
analysis will then take into account that white "wants" a draw, even when you
are analyzing a position where it is black's turn to move.
AutoContempt
When AutoContempt is set to true, the Contempt option is ignored and the
contempt value during game play is instead determined based on the opponent as
defined by the ContemptFile option.
ContemptFile
Used when AutoContempt is set to true. Specifies the path to the text file
that defines what contempt value to use for a given opponent. Each line in the
file has the format regex <tab> contempt. The regular expression has the C++
ECMAScript format, see http://en.cppreference.com/w/cpp/regex/ecmascript.
The regular expression is matched against the value of the UCI_Opponent
option, which should be set automatically by the GUI.
Example:
\w+ \w+ \w+ AlphaZero.* -100
.* 0
GaviotaTbPath
Semicolon separated list of directories that will be searched for Gaviota
tablebase files (*.gtb.cp4).
GaviotaTbCache
Gaviota tablebase cache size in megabytes.
SyzygyPath
Semicolon (Windows) or colon (Linux, Android) separated list of directories
that will be searched for Syzygy tablebase files.
MinProbeDepth
Minimum remaining search depth required to probe tablebases. If tablebase
probing slows down the engine too much, try making this value larger. If all
tablebase files are on fast SSD drives or cached in RAM, a value of 0 or 1 can
probably be used without much slowdown.
MinProbeDepth6, MinProbeDepth7
Minimum remaining search depth required to probe 6-men and 7-men tablebases.
Values smaller than MinProbeDepth are ignored. Values larger than
MinProbeDepth can be useful if the larger tablebases are on slower disks than
the smaller tablebases.
MinProbeDepth6dtz, MinProbeDepth7dtz
Minimum remaining search depth required to probe 6-men and 7-men DTZ
tablebases. Values smaller than MinProbeDepth6, MinProbeDepth7 are ignored.
Values larger than MinProbeDepth6/7 can be useful if DTZ tables are on slower
disks than WDL tables.
Clear Hash
When activated, clears the hash table and the history heuristic table, so that
the next search behaves as if the engine had just been started.
AnalysisAgeHash
When set to false the transposition table is not "aged" when starting a new
search in analysis mode. This helps keeping older but deeper entries around in
the transposition table, which is useful when analysing a position and making
and un-making moves to explore the position.
Tablebases
----------
Texel can use endgame tablebases to improve game play and analysis in the
endgame. Both Gaviota tablebases (only .cp4 compression) and Syzygy tablebases
are supported, and both tablebase types can be used simultaneously.
For game play Syzygy tablebases are recommended because the Syzygy probing code
scales better when the engine uses multiple cores.
For analysis, using both Syzygy and Gaviota tablebases at the same time is
recommended. This gives accurate mate scores and PVs when the search can reach a
5-men position (thanks to Gaviota tablebases), and game theoretically correct
results (also taking 50-move draws into account) when the search can reach a
6-men position (thanks to Syzygy tablebases).
Syzygy tablebases contain distance to zeroing move (DTZ) information instead of
distance to mate (DTM) information. DTZ values are converted internally to upper
or lower DTM bounds before being presented to the user. This means that there is
no separate score range for known tablebase wins, but it also means that the
shortest possible mate can be much shorter than the reported mate score
indicates.
For syzygy tablebases it is recommended to have the corresponding DTZ table for
each WDL table. Texel tries to handle missing tablebase files gracefully, but in
some situations missing DTZ tables may lead to trouble converting a won
tablebase position. This can happen even in relatively simple endgames that
Texel could have won without using tablebases at all.
Because of technicalities in the Syzygy probing code, 6-men tablebases are only
supported for the 64-bit versions of Texel.
The 6-men Syzygy tablebases will likely only increase the playing strength of
Texel if at least the WDL tables are stored on SSD.
NUMA
----
Non-uniform memory access (NUMA) is a computer memory design common in computers
that have more than one CPU. Texel can take advantage of NUMA hardware when
running on Windows or Linux.
The pre-compiled 64-bit Windows executables are compiled with NUMA awareness.
The pre-compiled Linux executable is not NUMA aware because it adds a dependency
on the libnuma library which may not be installed on all Linux systems.
When running a NUMA aware executable, NUMA awareness can be disabled at runtime
by giving the -nonuma argument when starting Texel.
When NUMA awareness is enabled and Texel runs on NUMA hardware, Texel binds its
search threads to suitable NUMA nodes and tries to allocate thread-local memory
on the same nodes as the threads run on. If Texel uses fewer search threads than
there are cores in the computer, the threads will be bound to NUMA nodes such
that there are no more than one thread per core and such that as few NUMA nodes
as possible are used. This arrangement speeds up memory accesses.
Cluster
-------
Texel can run on computer clusters by using the MPI system. It has only been
tested using MPICH in Linux and MS-MPI in Windows but should work with other MPI
implementations as well.
The pre-compiled windows executable texel64cl.exe is compiled and linked against
MS-MPI version 8.1. It requires the MS-MPI redistributable package to be
installed and configured on all computers in the cluster.
Running on a cluster is an advanced functionality and probably requires some
knowledge of cluster systems to set up.
Texel uses a so called hybrid MPI design. This means that it uses a single MPI
process per computer. On each computer it uses threads and shared memory, and
optionally NUMA awareness.
After Texel has been started, use the "Threads" UCI option to control the total
number of search threads to use. Texel automatically decides how many threads to
use for each computer, and can also handle the case where different computers
have different number of CPUs and cores.
* Example using MPICH and Linux:
If there are 4 Linux computers called host1, host2, host3, host4 and
MPICH is installed on all computers, start Texel like this:
mpiexec -hosts host1,host2,host3,host4 /path/to/texel
Note that /path/to/texel must be valid for all computers in the cluster, so
either install Texel on all computers or install it on a network disk that is
mounted on all computers.
Note that it must be possible to ssh from host1 to the other hosts without
specifying a password. Use for example ssh-agent and ssh-add to achieve this.
* Example using MS-MPI and Windows:
If there are two computers called host1 and host2 and MS-MPI is installed on
both computers, proceed as follows:
1. On all computers, log in as the same user.
2. On all computers, add firewall exceptions to allow the programs mpiexec and
smpd (located in C:\Program Files\Microsoft MPI\Bin) to communicate over the
network.
3. On all computers, start a command prompt and execute:
smpd -d 0
4. Make sure Texel is installed in the same directory on all computers.
5. On the host1 computer, start a command prompt and execute:
cd /directory/where/texel/is/installed
mpiexec -hosts 2 host1 host2 texel64cl.exe
* Running the cluster version in a GUI
To run the cluster version of Texel in a GUI, the engine should be defined as
the mpiexec command with all parameters as given in the examples above. If the
GUI does not support adding command line parameters to the engine you can use a
wrapper program that passes the required parameters to mpiexec. If you are using
Linux, creating a one-line shell script should be enough. If you are using
Windows, you can use the included runcmd.exe program:
1. Copy the runcmd.exe program to the directory where Texel is located.
2. In the same directory create a text file called runcmd.txt that contains the
mpiexec command to run. Make sure the file ends with a newline character.
3. Install the runcmd.exe program as a UCI engine in the GUI.
Compiling
---------
Texel uses the CMake build system. To compile Texel follow these steps, assuming
you have access to a terminal environment:
1. cd <directory_where_texel_was_unpacked>
2. mkdir build
3. cd build
4. cmake ..
5. Run "cmake-gui ."
- Enable desired options
- Click "Generate"
- Exit cmake-gui
6. make -j8
7. ./texel
The following options can be enabled to activate CPU, OS and compiler specific
features. Not all options are available for all operating systems and compilers:
USE_SSSE3
Use SSSE3 instructions to speed up neural network evaluation.
USE_AVX2
Use AVX2 instructions to speed up neural network evaluation.
USE_AVX512
Use AVX-512 instructions to speed up neural network evaluation.
USE_BMI2
Use BMI2 instructions to speed up move generation.
USE_POPCNT
Use CPU popcount instructions to speed up counting of number of 1 bits in a
bitboard object.
USE_NEON
Use NEON instructions (for ARM CPUs) to speed up neural network evaluation.
USE_NEON_DOT
Use NEON and dot product instructions (for ARM CPUs) to speed up neural
network evaluation.
USE_CTZ
Use a special CPU instruction to find the first 1 bit in a bitboard object.
USE_PREFETCH
Use CPU prefetch instructions to speed up hash table access.
USE_NUMA
Optimize thread affinity and memory allocations when running on NUMA hardware.
USE_LARGE_PAGES
Prefer large pages when allocating memory for the transposition table. Only
effective if large page support is enabled in the operating system. For Linux
systems an alternative to using this option is to execute the following
command as root:
echo always >/sys/kernel/mm/transparent_hugepage/enabled
USE_CLUSTER
Use MPI to distribute the search to several computers connected in a cluster.
USE_WIN7
Compile for Windows 7 and later versions. This is required to be able to take
advantage of large computers that have more than 64 hardware threads.
Additional source code
----------------------
Source code for Texel's automatic test suite is provided in the test directory.
Source code for various tools used during Texel development is provided in the
app/texelutil directory. This program depends on the libraries Armadillo and GSL
for full functionality.
Source code for neural network training is provided in the app/torchutil
directory. This program depends on LibTorch, which is the C++ part of PyTorch.
Source code for an interactive interface to the Texel book building algorithm is
provided in the app/bookgui directory. It depends on gtkmm-3.0 and probably only
works in Linux.
Some utilities require access to tablebases. Set the environment variables
GTBPATH and RTBPATH to specify where the tablebase files are located.
Copyright
---------
The core Texel chess engine is developed by Peter Österlund, but Texel also
contains auxiliary code written by other people:
Gaviota Tablebases Probing Code, Copyright 2010 Miguel A. Ballicora.
See lib/texellib/gtb/readme.txt for more information.
LZMA compression by Igor Pavlov, used by the Gaviota Tablebases Probing code.
Syzygy tablebases probing code, Copyright 2011-2013 Ronald de Man.
Chess Cases font by Matthieu Leschemelle, used by the opening book builder
graphical user interface.
Google Test framework, Copyright 2008, Google Inc.