diff --git a/README.md b/README.md
index ca90d5d4..1f462d31 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,21 @@
[![Stockfish][stockfish128-logo]][website-link]
+ Stockfish
+
+ A free and strong UCI chess engine.
+
+ [Explore Stockfish docs »][wiki-link]
+
+
+ [Report bug][issue-link]
+ ·
+ [Open a discussion][discussions-link]
+ ·
+ [Discord][discord-link]
+ ·
+ [Blog][website-blog-link]
+
[![Build][build-badge]][build-link]
[![License][license-badge]][license-link]
@@ -16,19 +31,16 @@
## Overview
-[Stockfish][website-link] 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][website-link] is a **free and strong UCI chess engine** derived from
+Glaurung 2.1 that analyzes chess positions and computes the optimal moves.
+
+Stockfish **does not include a graphical user interface** (GUI) that is required
+to display a chessboard and to make it easy to input moves. These GUIs are
+developed independently from Stockfish and are available online. **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 efficiently
-updatable neural network (NNUE) based evaluation is the default and by far the strongest.
-The classical evaluation based on handcrafted terms remains available. The strongest
-network is integrated in the binary and downloaded automatically during the build process.
-The NNUE evaluation benefits from the vector intrinsics available on most CPUs (sse2,
-avx2, neon, or similar).
+See also the Stockfish [documentation][wiki-usage-link] for further usage help.
## Files
@@ -36,338 +48,112 @@ This distribution of Stockfish consists of the following files:
* [README.md][readme-link], the file you are currently reading.
- * [Copying.txt][license-link], a text file containing the GNU General Public License
- version 3.
+ * [Copying.txt][license-link], a text file containing the GNU General Public
+ License version 3.
* [AUTHORS][authors-link], a text file with the list of authors for the project.
- * [src][src-link], a subdirectory containing the full source code, including a Makefile
- that can be used to compile Stockfish on Unix-like systems.
+ * [src][src-link], 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.
+ * 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 UCI protocol
-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 its options as described
-in [the UCI protocol][uci-link].
+The [Universal Chess Interface][uci-link] (UCI) is a standard text-based 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 its options.
-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:
+Developers can see the default values for the UCI options available in Stockfish
+by typing `./stockfish uci` in a terminal, but most users should typically use a
+chess GUI to interact with 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.
+For more information on UCI or debug commands, see our [documentation][wiki-commands-link].
- * #### Hash
- The size of the hash table in MB. It is recommended to set Hash after setting Threads.
+## Compiling Stockfish
- * #### Clear Hash
- Clear the hash table.
+Stockfish has support for 32 or 64-bit CPUs, certain hardware instructions,
+big-endian machines such as Power PC, and other platforms.
- * #### 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 120s+1.0s and anchored to +- 100 Elo to CCRL Blitz.
-
- * #### 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 HDD. 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][nodchip-link] provided the first version of the needed tools
-to train and develop the NNUE networks. Today, more advanced training tools are
-available in [the nnue-pytorch repository][pytorch-link], while data generation tools
-are available in [a dedicated branch][tools-link].
-
-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)][lockpages-link]
-on how to enable this privilege, then run [RAMMap][rammap-link]
-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.
+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
+cd src
+make -j 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.
+Detailed compilation instructions for all platforms can be found in our
+[documentation][wiki-compile-link].
-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.
+## Contributing
### Donating hardware
-Improving Stockfish requires a massive amount of testing. You can donate
-your hardware resources by installing the [Fishtest Worker][worker-link]
-and view the current tests on [Fishtest][fishtest-link].
+Improving Stockfish requires a massive amount of testing. You can donate your
+hardware resources by installing the [Fishtest Worker][worker-link] and viewing
+the current tests on [Fishtest][fishtest-link].
### Improving the code
-If you want to help improve the code, there are several valuable resources:
-
-* [In this wiki,][programming-link] many techniques used in
+In the [chessprogramming wiki][programming-link], many techniques used in
Stockfish are explained with a lot of background information.
+The [section on Stockfish][programmingsf-link] describes many features
+and techniques used by Stockfish. However, it is generic rather than
+focused on Stockfish's precise implementation.
-* [The section on Stockfish][programmingsf-link]
-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][github-link].
-Discussions about Stockfish take place these days mainly in the [FishCooking][fishcooking-link]
-group and on the [Stockfish Discord channel][discord-link].
The engine testing is done on [Fishtest][fishtest-link].
If you want to help improve Stockfish, please read this [guideline][guideline-link]
first, where the basics of Stockfish development are explained.
+Discussions about Stockfish take place these days mainly in the Stockfish
+[Discord server][discord-link]. This is also the best place to ask questions
+about the codebase and how to improve it.
## 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.
+Stockfish is free and distributed under the
+[**GNU General Public License version 3**][license-link] (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 license and 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 v3.
-
-For full details, read the copy of the GPL v3 found in the file named
-[*Copying.txt*][license-link].
+The only real limitation is that whenever you distribute Stockfish in some way,
+you MUST always include the license and 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 GPL v3.
[authors-link]: https://github.com/official-stockfish/Stockfish/blob/master/AUTHORS
[build-link]: https://github.com/official-stockfish/Stockfish/actions/workflows/stockfish.yml
[commits-link]: https://github.com/official-stockfish/Stockfish/commits/master
[discord-link]: https://discord.gg/GWDRS3kU6R
-[fishcooking-link]: https://groups.google.com/g/fishcooking
+[issue-link]: https://github.com/official-stockfish/Stockfish/issues/new?assignees=&labels=&template=BUG-REPORT.yml
+[discussions-link]: https://github.com/official-stockfish/Stockfish/discussions/new
[fishtest-link]: https://tests.stockfishchess.org/tests
-[github-link]: https://github.com/official-stockfish/Stockfish
[guideline-link]: https://github.com/glinscott/fishtest/wiki/Creating-my-first-test
[license-link]: https://github.com/official-stockfish/Stockfish/blob/master/Copying.txt
-[lockpages-link]: https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/enable-the-lock-pages-in-memory-option-windows
-[nodchip-link]: https://github.com/nodchip/Stockfish
[programming-link]: https://www.chessprogramming.org/Main_Page
[programmingsf-link]: https://www.chessprogramming.org/Stockfish
-[pytorch-link]: https://github.com/glinscott/nnue-pytorch
-[rammap-link]: https://docs.microsoft.com/en-us/sysinternals/downloads/rammap
[readme-link]: https://github.com/official-stockfish/Stockfish/blob/master/README.md
[release-link]: https://github.com/official-stockfish/Stockfish/releases/latest
[src-link]: https://github.com/official-stockfish/Stockfish/tree/master/src
[stockfish128-logo]: https://stockfishchess.org/images/logo/icon_128x128.png
-[tools-link]: https://github.com/official-stockfish/Stockfish/tree/tools
-[uci-link]: https://www.shredderchess.com/download/div/uci.zip
+[uci-link]: https://backscattering.de/chess/uci/
[website-link]: https://stockfishchess.org
-[worker-link]: https://github.com/glinscott/fishtest/wiki/Running-the-worker:-overview
+[website-blog-link]: https://stockfishchess.org/blog/
+[wiki-link]: https://github.com/official-stockfish/Stockfish/wiki
+[wiki-usage-link]: https://github.com/official-stockfish/Stockfish/wiki/Download-and-usage
+[wiki-compile-link]: https://github.com/official-stockfish/Stockfish/wiki/Compiling-from-source
+[wiki-commands-link]: https://github.com/official-stockfish/Stockfish/wiki/Commands
+[worker-link]: https://github.com/glinscott/fishtest/wiki/Running-the-worker
[build-badge]: https://img.shields.io/github/actions/workflow/status/official-stockfish/Stockfish/stockfish.yml?branch=master&style=for-the-badge&label=stockfish&logo=github
[commits-badge]: https://img.shields.io/github/commits-since/official-stockfish/Stockfish/latest?style=for-the-badge