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.

Warning

Ensure tablebase files match the known checksums. Maliciously crafted tablebase files may cause denial of service with PythonTablebase and memory unsafety with NativeTablebase.

chess.gaviota.open_tablebase(directory: str, *, libgtb: str | None = None, LibraryLoader: ~ctypes.LibraryLoader[~ctypes.CDLL] = <ctypes.LibraryLoader object>) → NativeTablebase | PythonTablebase

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

Provides access to Gaviota tablebases using pure Python code.

add_directory(directory: str) → None

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

probe_dtm(board: Board) → int

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: Board) → int

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

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: str, *, libgtb: str | None = None, LibraryLoader: ~ctypes.LibraryLoader[~ctypes.CDLL] = <ctypes.LibraryLoader object>) → NativeTablebase

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: CDLL)

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