Gaviota endgame tablebase probing

Gaviota tablebases provide WDL (win/draw/loss) and DTM (depth to mate) information for all endgame positions with up to 5 pieces. Positions with castling rights are not included.

chess.gaviota.open_tablebase(directory: Union[str, bytes], *, libgtb: Any = None, LibraryLoader: Any = <ctypes.LibraryLoader object>) → Union[chess.gaviota.NativeTablebase, chess.gaviota.PythonTablebase][source]

Opens a collection of tables for probing.

First native access via the shared library libgtb is tried. You can optionally provide a specific library name or a library loader. The shared library has global state and caches, so only one instance can be open at a time.

Second, pure Python probing code is tried.

class chess.gaviota.PythonTablebase[source]

Provides access to Gaviota tablebases using pure Python code.

add_directory(directory: Union[str, bytes]) → None[source]

Adds .gtb.cp4 tables from a directory. The relevant files are lazily opened when the tablebase is actually probed.

probe_dtm(board: chess.Board) → int[source]

Probes for depth to mate information.

The absolute value is the number of half-moves until forced mate (or 0 in drawn positions). The value is positive if the side to move is winning, otherwise it is negative.

In the example position white to move will get mated in 10 half-moves:

>>> import chess
>>> import chess.gaviota
>>>
>>> with chess.gaviota.open_tablebase("data/gaviota") as tablebase:
...     board = chess.Board("8/8/8/8/8/8/8/K2kr3 w - - 0 1")
...     print(tablebase.probe_dtm(board))
...
-10
Raises:

KeyError (or specifically chess.gaviota.MissingTableError) if the probe fails. Use get_dtm() if you prefer to get None instead of an exception.

Note that probing a corrupted table file is undefined behavior.

probe_wdl(board: chess.Board) → int[source]

Probes for win/draw/loss-information.

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

>>> import chess
>>> import chess.gaviota
>>>
>>> with chess.gaviota.open_tablebase("data/gaviota") as tablebase:
...     board = chess.Board("8/4k3/8/B7/8/8/8/4K3 w - - 0 1")
...     print(tablebase.probe_wdl(board))
...
0
Raises:

KeyError (or specifically chess.gaviota.MissingTableError) if the probe fails. Use get_wdl() if you prefer to get None instead of an exception.

Note that probing a corrupted table file is undefined behavior.

close() → None[source]

Closes all loaded tables.

libgtb

For faster access you can build and install a shared library. Otherwise the pure Python probing code is used.

git clone https://github.com/michiguel/Gaviota-Tablebases.git
cd Gaviota-Tablebases
make
sudo make install
chess.gaviota.open_tablebase_native(directory: Union[str, bytes], *, libgtb: Any = None, LibraryLoader: Any = <ctypes.LibraryLoader object>) → chess.gaviota.NativeTablebase[source]

Opens a collection of tables for probing using libgtb.

In most cases open_tablebase() should be used. Use this function only if you do not want to downgrade to pure Python tablebase probing.

Raises:RuntimeError or OSError when libgtb can not be used.
class chess.gaviota.NativeTablebase(libgtb: Any)[source]

Provides access to Gaviota tablebases via the shared library libgtb. Has the same interface as PythonTablebase.