328 lines
15 KiB
Markdown
328 lines
15 KiB
Markdown
## Overview
|
|
|
|
[](https://github.com/official-stockfish/Stockfish/actions)
|
|
[](https://ci.appveyor.com/project/mcostalba/stockfish/branch/master)
|
|
|
|
[Stockfish](https://stockfishchess.org) is a free, powerful UCI chess engine
|
|
derived from Glaurung 2.1. Stockfish is not a complete chess program and requires a
|
|
UCI-compatible graphical user interface (GUI) (e.g. XBoard with PolyGlot, Scid,
|
|
Cute Chess, eboard, Arena, Sigma Chess, Shredder, Chess Partner or Fritz) in order
|
|
to be used comfortably. Read the documentation for your GUI of choice for information
|
|
about how to use Stockfish with it.
|
|
|
|
The Stockfish engine features two evaluation functions for chess, the classical
|
|
evaluation based on handcrafted terms, and the NNUE evaluation based on efficiently
|
|
updatable neural networks. The classical evaluation runs efficiently on almost all
|
|
CPU architectures, while the NNUE evaluation benefits from the vector
|
|
intrinsics available on most CPUs (sse2, avx2, neon, or similar).
|
|
|
|
|
|
## Files
|
|
|
|
This distribution of Stockfish consists of the following files:
|
|
|
|
* [Readme.md](https://github.com/official-stockfish/Stockfish/blob/master/README.md), the file you are currently reading.
|
|
|
|
* [Copying.txt](https://github.com/official-stockfish/Stockfish/blob/master/Copying.txt), a text file containing the GNU General Public License version 3.
|
|
|
|
* [AUTHORS](https://github.com/official-stockfish/Stockfish/blob/master/AUTHORS), a text file with the list of authors for the project
|
|
|
|
* [src](https://github.com/official-stockfish/Stockfish/tree/master/src), a subdirectory containing the full source code, including a Makefile
|
|
that can be used to compile Stockfish on Unix-like systems.
|
|
|
|
* a file with the .nnue extension, storing the neural network for the NNUE
|
|
evaluation. Binary distributions will have this file embedded.
|
|
|
|
## The UCI protocol and available options
|
|
|
|
The Universal Chess Interface (UCI) is a standard protocol used to communicate with
|
|
a chess engine, and is the recommended way to do so for typical graphical user interfaces
|
|
(GUI) or chess tools. Stockfish implements the majority of it options as described
|
|
in [the UCI protocol](https://www.shredderchess.com/download/div/uci.zip).
|
|
|
|
Developers can see the default values for UCI options available in Stockfish by typing
|
|
`./stockfish uci` in a terminal, but the majority of users will typically see them and
|
|
change them via a chess GUI. This is a list of available UCI options in Stockfish:
|
|
|
|
* #### Threads
|
|
The number of CPU threads used for searching a position. For best performance, set
|
|
this equal to the number of CPU cores available.
|
|
|
|
* #### Hash
|
|
The size of the hash table in MB. It is recommended to set Hash after setting Threads.
|
|
|
|
* #### Clear Hash
|
|
Clear the hash table.
|
|
|
|
* #### Ponder
|
|
Let Stockfish ponder its next move while the opponent is thinking.
|
|
|
|
* #### MultiPV
|
|
Output the N best lines (principal variations, PVs) when searching.
|
|
Leave at 1 for best performance.
|
|
|
|
* #### Use NNUE
|
|
Toggle between the NNUE and classical evaluation functions. If set to "true",
|
|
the network parameters must be available to load from file (see also EvalFile),
|
|
if they are not embedded in the binary.
|
|
|
|
* #### EvalFile
|
|
The name of the file of the NNUE evaluation parameters. Depending on the GUI the
|
|
filename might have to include the full path to the folder/directory that contains the file.
|
|
Other locations, such as the directory that contains the binary and the working directory,
|
|
are also searched.
|
|
|
|
* #### UCI_AnalyseMode
|
|
An option handled by your GUI.
|
|
|
|
* #### UCI_Chess960
|
|
An option handled by your GUI. If true, Stockfish will play Chess960.
|
|
|
|
* #### UCI_ShowWDL
|
|
If enabled, show approximate WDL statistics as part of the engine output.
|
|
These WDL numbers model expected game outcomes for a given evaluation and
|
|
game ply for engine self-play at fishtest LTC conditions (60+0.6s per game).
|
|
|
|
* #### UCI_LimitStrength
|
|
Enable weaker play aiming for an Elo rating as set by UCI_Elo. This option overrides Skill Level.
|
|
|
|
* #### UCI_Elo
|
|
If enabled by UCI_LimitStrength, aim for an engine strength of the given Elo.
|
|
This Elo rating has been calibrated at a time control of 60s+0.6s and anchored to CCRL 40/4.
|
|
|
|
* #### Skill Level
|
|
Lower the Skill Level in order to make Stockfish play weaker (see also UCI_LimitStrength).
|
|
Internally, MultiPV is enabled, and with a certain probability depending on the Skill Level a
|
|
weaker move will be played.
|
|
|
|
* #### SyzygyPath
|
|
Path to the folders/directories storing the Syzygy tablebase files. Multiple
|
|
directories are to be separated by ";" on Windows and by ":" on Unix-based
|
|
operating systems. Do not use spaces around the ";" or ":".
|
|
|
|
Example: `C:\tablebases\wdl345;C:\tablebases\wdl6;D:\tablebases\dtz345;D:\tablebases\dtz6`
|
|
|
|
It is recommended to store .rtbw files on an SSD. There is no loss in storing
|
|
the .rtbz files on a regular HD. It is recommended to verify all md5 checksums
|
|
of the downloaded tablebase files (`md5sum -c checksum.md5`) as corruption will
|
|
lead to engine crashes.
|
|
|
|
* #### SyzygyProbeDepth
|
|
Minimum remaining search depth for which a position is probed. Set this option
|
|
to a higher value to probe less aggressively if you experience too much slowdown
|
|
(in terms of nps) due to tablebase probing.
|
|
|
|
* #### Syzygy50MoveRule
|
|
Disable to let fifty-move rule draws detected by Syzygy tablebase probes count
|
|
as wins or losses. This is useful for ICCF correspondence games.
|
|
|
|
* #### SyzygyProbeLimit
|
|
Limit Syzygy tablebase probing to positions with at most this many pieces left
|
|
(including kings and pawns).
|
|
|
|
* #### Move Overhead
|
|
Assume a time delay of x ms due to network and GUI overheads. This is useful to
|
|
avoid losses on time in those cases.
|
|
|
|
* #### Slow Mover
|
|
Lower values will make Stockfish take less time in games, higher values will
|
|
make it think longer.
|
|
|
|
* #### nodestime
|
|
Tells the engine to use nodes searched instead of wall time to account for
|
|
elapsed time. Useful for engine testing.
|
|
|
|
* #### Debug Log File
|
|
Write all communication to and from the engine into a text file.
|
|
|
|
For developers the following non-standard commands might be of interest, mainly useful for debugging:
|
|
|
|
* #### bench *ttSize threads limit fenFile limitType evalType*
|
|
Performs a standard benchmark using various options. The signature of a version (standard node
|
|
count) is obtained using all defaults. `bench` is currently `bench 16 1 13 default depth mixed`.
|
|
|
|
* #### compiler
|
|
Give information about the compiler and environment used for building a binary.
|
|
|
|
* #### d
|
|
Display the current position, with ascii art and fen.
|
|
|
|
* #### eval
|
|
Return the evaluation of the current position.
|
|
|
|
* #### export_net [filename]
|
|
Exports the currently loaded network to a file.
|
|
If the currently loaded network is the embedded network and the filename
|
|
is not specified then the network is saved to the file matching the name
|
|
of the embedded network, as defined in evaluate.h.
|
|
If the currently loaded network is not the embedded network (some net set
|
|
through the UCI setoption) then the filename parameter is required and the
|
|
network is saved into that file.
|
|
|
|
* #### flip
|
|
Flips the side to move.
|
|
|
|
|
|
## A note on classical evaluation versus NNUE evaluation
|
|
|
|
Both approaches assign a value to a position that is used in alpha-beta (PVS) search
|
|
to find the best move. The classical evaluation computes this value as a function
|
|
of various chess concepts, handcrafted by experts, tested and tuned using fishtest.
|
|
The NNUE evaluation computes this value with a neural network based on basic
|
|
inputs (e.g. piece positions only). The network is optimized and trained
|
|
on the evaluations of millions of positions at moderate search depth.
|
|
|
|
The NNUE evaluation was first introduced in shogi, and ported to Stockfish afterward.
|
|
It can be evaluated efficiently on CPUs, and exploits the fact that only parts
|
|
of the neural network need to be updated after a typical chess move.
|
|
[The nodchip repository](https://github.com/nodchip/Stockfish) provides additional
|
|
tools to train and develop the NNUE networks. On CPUs supporting modern vector instructions
|
|
(avx2 and similar), the NNUE evaluation results in much stronger playing strength, even
|
|
if the nodes per second computed by the engine is somewhat lower (roughly 80% of nps
|
|
is typical).
|
|
|
|
Notes:
|
|
|
|
1) the NNUE evaluation depends on the Stockfish binary and the network parameter
|
|
file (see the EvalFile UCI option). Not every parameter file is compatible with a given
|
|
Stockfish binary, but the default value of the EvalFile UCI option is the name of a network
|
|
that is guaranteed to be compatible with that binary.
|
|
|
|
2) to use the NNUE evaluation, the additional data file with neural network parameters
|
|
needs to be available. Normally, this file is already embedded in the binary or it
|
|
can be downloaded. The filename for the default (recommended) net can be found as the default
|
|
value of the `EvalFile` UCI option, with the format `nn-[SHA256 first 12 digits].nnue`
|
|
(for instance, `nn-c157e0a5755b.nnue`). This file can be downloaded from
|
|
```
|
|
https://tests.stockfishchess.org/api/nn/[filename]
|
|
```
|
|
replacing `[filename]` as needed.
|
|
|
|
## What to expect from the Syzygy tablebases?
|
|
|
|
If the engine is searching a position that is not in the tablebases (e.g.
|
|
a position with 8 pieces), it will access the tablebases during the search.
|
|
If the engine reports a very large score (typically 153.xx), this means
|
|
it has found a winning line into a tablebase position.
|
|
|
|
If the engine is given a position to search that is in the tablebases, it
|
|
will use the tablebases at the beginning of the search to preselect all
|
|
good moves, i.e. all moves that preserve the win or preserve the draw while
|
|
taking into account the 50-move rule.
|
|
It will then perform a search only on those moves. **The engine will not move
|
|
immediately**, unless there is only a single good move. **The engine likely
|
|
will not report a mate score, even if the position is known to be won.**
|
|
|
|
It is therefore clear that this behaviour is not identical to what one might
|
|
be used to with Nalimov tablebases. There are technical reasons for this
|
|
difference, the main technical reason being that Nalimov tablebases use the
|
|
DTM metric (distance-to-mate), while the Syzygy tablebases use a variation of the
|
|
DTZ metric (distance-to-zero, zero meaning any move that resets the 50-move
|
|
counter). This special metric is one of the reasons that the Syzygy tablebases are
|
|
more compact than Nalimov tablebases, while still storing all information
|
|
needed for optimal play and in addition being able to take into account
|
|
the 50-move rule.
|
|
|
|
## Large Pages
|
|
|
|
Stockfish supports large pages on Linux and Windows. Large pages make
|
|
the hash access more efficient, improving the engine speed, especially
|
|
on large hash sizes. Typical increases are 5..10% in terms of nodes per
|
|
second, but speed increases up to 30% have been measured. The support is
|
|
automatic. Stockfish attempts to use large pages when available and
|
|
will fall back to regular memory allocation when this is not the case.
|
|
|
|
### Support on Linux
|
|
|
|
Large page support on Linux is obtained by the Linux kernel
|
|
transparent huge pages functionality. Typically, transparent huge pages
|
|
are already enabled, and no configuration is needed.
|
|
|
|
### Support on Windows
|
|
|
|
The use of large pages requires "Lock Pages in Memory" privilege. See
|
|
[Enable the Lock Pages in Memory Option (Windows)](https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/enable-the-lock-pages-in-memory-option-windows)
|
|
on how to enable this privilege, then run [RAMMap](https://docs.microsoft.com/en-us/sysinternals/downloads/rammap)
|
|
to double-check that large pages are used. We suggest that you reboot
|
|
your computer after you have enabled large pages, because long Windows
|
|
sessions suffer from memory fragmentation, which may prevent Stockfish
|
|
from getting large pages: a fresh session is better in this regard.
|
|
|
|
## Compiling Stockfish yourself from the sources
|
|
|
|
Stockfish has support for 32 or 64-bit CPUs, certain hardware
|
|
instructions, big-endian machines such as Power PC, and other platforms.
|
|
|
|
On Unix-like systems, it should be easy to compile Stockfish
|
|
directly from the source code with the included Makefile in the folder
|
|
`src`. In general it is recommended to run `make help` to see a list of make
|
|
targets with corresponding descriptions.
|
|
|
|
```
|
|
cd src
|
|
make help
|
|
make net
|
|
make build ARCH=x86-64-modern
|
|
```
|
|
|
|
When not using the Makefile to compile (for instance, with Microsoft MSVC) you
|
|
need to manually set/unset some switches in the compiler command line; see
|
|
file *types.h* for a quick reference.
|
|
|
|
When reporting an issue or a bug, please tell us which Stockfish version
|
|
and which compiler you used to create your executable. This information
|
|
can be found by typing the following command in a console:
|
|
|
|
```
|
|
./stockfish compiler
|
|
```
|
|
|
|
## Understanding the code base and participating in the project
|
|
|
|
Stockfish's improvement over the last decade has been a great community
|
|
effort. There are a few ways to help contribute to its growth.
|
|
|
|
### Donating hardware
|
|
|
|
Improving Stockfish requires a massive amount of testing. You can donate
|
|
your hardware resources by installing the [Fishtest Worker](https://github.com/glinscott/fishtest/wiki/Running-the-worker:-overview)
|
|
and view the current tests on [Fishtest](https://tests.stockfishchess.org/tests).
|
|
|
|
### Improving the code
|
|
|
|
If you want to help improve the code, there are several valuable resources:
|
|
|
|
* [In this wiki,](https://www.chessprogramming.org) many techniques used in
|
|
Stockfish are explained with a lot of background information.
|
|
|
|
* [The section on Stockfish](https://www.chessprogramming.org/Stockfish)
|
|
describes many features and techniques used by Stockfish. However, it is
|
|
generic rather than being focused on Stockfish's precise implementation.
|
|
Nevertheless, a helpful resource.
|
|
|
|
* The latest source can always be found on [GitHub](https://github.com/official-stockfish/Stockfish).
|
|
Discussions about Stockfish take place these days mainly in the [FishCooking](https://groups.google.com/forum/#!forum/fishcooking)
|
|
group and on the [Stockfish Discord channel](https://discord.gg/nv8gDtt).
|
|
The engine testing is done on [Fishtest](https://tests.stockfishchess.org/tests).
|
|
If you want to help improve Stockfish, please read this [guideline](https://github.com/glinscott/fishtest/wiki/Creating-my-first-test)
|
|
first, where the basics of Stockfish development are explained.
|
|
|
|
|
|
## Terms of use
|
|
|
|
Stockfish is free, and distributed under the **GNU General Public License version 3**
|
|
(GPL v3). Essentially, this means you are free to do almost exactly
|
|
what you want with the program, including distributing it among your
|
|
friends, making it available for download from your website, selling
|
|
it (either by itself or as part of some bigger software package), or
|
|
using it as the starting point for a software project of your own.
|
|
|
|
The only real limitation is that whenever you distribute Stockfish in
|
|
some way, you MUST always include the full source code, or a pointer
|
|
to where the source code can be found, to generate the exact binary
|
|
you are distributing. If you make any changes to the source code,
|
|
these changes must also be made available under the GPL.
|
|
|
|
For full details, read the copy of the GPL v3 found in the file named
|
|
[*Copying.txt*](https://github.com/official-stockfish/Stockfish/blob/master/Copying.txt).
|