Syzygy endgame tablebase probing

Syzygy tablebases provide WDL (win/draw/loss) and DTZ (distance to zero) information for all endgame positions with up to 6 pieces. Positions with castling rights are not included.

chess.syzygy.open_tablebases(directory=None, load_wdl=True, load_dtz=True)

Opens a collection of tablebases for probing. See Tablebases.

class chess.syzygy.Tablebases(directory=None, load_wdl=True, load_dtz=True)

Manages a collection of tablebase files for probing.

Syzygy tables come in files like KQvKN.rtbw or KRBvK.rtbz, one WDL (.rtbw) and DTZ (.rtbz) file for each material composition.

Directly loads tables from directory. See open_directory().

open_directory(directory, load_wdl=True, load_dtz=True)

Loads tables from a directory.

By default all available tables with the correct file names (e.g. KQvKN.rtbw or KRBvK.rtbz) are loaded.

Returns the number of successfully openened and loaded tablebase files.

probe_wdl(board)

Probes WDL tables for win/draw/loss-information.

Probing is thread-safe when done with different board objects and if board objects are not modified during probing.

Returns None if the position was not found in any of the loaded tables.

Returns 2 if the side to move is winning, 0 if the position is a draw and -2 if the side to move is losing.

Returns 1 in case of a cursed win and -1 in case of a blessed loss. Mate can be forced but the position can be drawn due to the fifty-move rule.

>>> with chess.syzygy.open_tablebases("data/syzygy") as tablebases:
...     tablebases.probe_wdl(chess.Board("8/2K5/4B3/3N4/8/8/4k3/8 b - - 0 1"))
...
-2
probe_dtz(board)

Probes DTZ tables for distance to zero information.

Probing is thread-safe when done with different board objects and if board objects are not modified during probing.

Return None if the position was not found in any of the loaded tables. Both DTZ and WDL tables are required in order to probe for DTZ values.

Returns a positive value if the side to move is winning, 0 if the position is a draw and a negative value if the side to move is losing.

A non-zero distance to zero means the number of halfmoves until the next pawn move or capture can be forced, keeping a won position. Minmaxing the DTZ values guarantees winning a won position (and drawing a drawn position), because it makes progress keeping the win in hand. However the lines are not always the most straightforward ways to win. Engines like Stockfish calculate themselves, checking with DTZ, but only play according to DTZ if they can not manage on their own.

>>> with chess.syzygy.open_tablebases("data/syzygy") as tablebases:
...     tablebases.probe_dtz(chess.Board("8/2K5/4B3/3N4/8/8/4k3/8 b - - 0 1"))
...
-53
close()

Closes all loaded tables.