NAME

Chess::Plisco::Tablebase::Syzygy - Perl interface to Syzygy endgame table bases

SYNOPSIS

$tb = Chess::Plisco::Tablebase::Syzygy->new("./3-4-5");

DESCRIPTION

The module Chess::Plisco::Tablebase::Syzygy allows access to end-game table bases in Syzygy format.

This module has been added in version 7.0.0.

Syzygy endgame tables have been developed by Ronald de Man. They store the outcome of every possible game of chess with up to 7 pieces. They allow probing for a win/draw/loss (WDL) or for the "distance to zero" (DTZ) for a particular position.

WDL (win/draw/loss)

These probes should be done during search. They simply give the information whether a mate can be forced in a particular position or not.

A probe only makes sense if the half move counter is 0, in other words after a pawn move or a capture. Rationale: If the WDL probe reports a win but that win happens to take exactly fifty moves, the position is really a draw, when the fifty move counter is not 0.

For an engine, this should normally not matter if it probes all positions wherer possible. But it can be a problem if because of missing tables one or more non-optimal quiet moves have been made.

Cursed Wins and Blessed Losses

While generating the tables, it turned out that there are quite a few positions with 7 pieces or less where a mate can be forced but not within 50 moves. A position where the side to move can force a mate but in more than 50 moves, is called a cursed win. A position where checkmate can be delivered to the side to move but even with optimal play from both sides but not within 50 moves is called a blessed loss.

Under normal circumstances such positions should be considered a draw because the side that is on loss can claim a draw.

For cursed wins and blessed losses, the results of DTZ probes may be off by one. In order to save space the least significant bit of the DTZ value is discarded. This should normally not matter because the positions are a draw under the 50-move-rule.

DTZ (distance to zero)

This gives the number of half moves that the side to move needs to force a reset of the half move clock to 0. This is not the distance to mate (DTM)!

The half move clock is reset to 0 when a pawn moves, a piece is captured, or one side loses castling rights by moving a king or rook from its initial position. Keep in mind, however, that positions with castling rights are not contained in the database!

Minimizing a positive DTZ will sooner or later force a mate but not necessarily in the most elegant manner. Minimizing a negative DTZ will result in optimal play.

To understand the difference, imagine end endgame king, queen, and rook against a lone king. Minimizing DTZ will ultimately lead to a move of one of these types:

- a checkmate

- a rook sacrifice

- a queen sacrifice

The last two options may not look too smart but once one of the not strictly necessary pieces has left the board, the next zero point will be checkmate.

If two engines play against each other, this is perfectly alright because there are no extra points for a mate with fewer moves. Trying to find it is a waste of CPU circles.

If, however, an engine is used for game analysis, it should only follow the DTZ strategy if the mate cannot be found in the time given.

Castling

The tablebase files do not contain positions where castling is possible. With a maximum of 7 pieces on the board such positions are relatively rare anyhow.

En Passant

The tablebase files so also not contain positions where en passant is possible. However, the library works around this limitation. If a position is probed where en passant is possible, the probed value is not returned immediately. Instead, all en passant captures are tried out and the resulting positions are probed as well. Depending on the outcome of these additional probes, the result is corrected accordingly.

Example 1: The initial probe reports a draw. But if a pawn can be captured en passant, the position may turn into a win.

Example 2: The initial probe reports a draw because of a stalemate. But it could happen that an en passant capture is possible. That means that the position is actually not a stalemate. Since the capture is the only legal move, it has to be done and the resulting game may be a loss.

CONSTRUCTOR

new PATH[, OPTIONS]

Initialize the database located at PATH.

Throws an exception in case of an error.

You may pass additional options as a hash reference OPTIONS:

load_wdl

Whether to load WDL files, default true.

load_dtz

Whether to load DTZ files, default true.

max_fds

Maximum number of open file descriptors, default 128.

recursive

Whether search recursively for files.

METHODS

probeWdl POSITION

Does a WDL probe for the Chess::Plisco object POSITION. Returns +2 for a forced win, -2 for a forced loss, 0 for a draw. All results take the 50 move rule into account. A return value of +1 means a cursed win, a return value of -1 is a blessed loss. These should also be considered a draw.

The method may throw an exception. One common cause is a missing table.

safeProbeWdl POSITION, DEFAULT

Like probeWdl() but returns DEFAULT if an exception occurs. If you omit DEFAULT, undefined is returned.

probeDtz POSITION

Does a DTZ probe for the Chess::Plisco object POSITION. It returns a positive value for positions where a mate can beforced, and a negative value for positions where a loss is unavoidable. A return value of 0 means a draw.

The absolute value of the return value gives the number of half moves until the winning side can force a reset of the half move counter to 0 either by a pawn move, a capture, or a checkmate.

safeProbeDtz POSITION, DEFAULT

Like probeDtz() but returns DEFAULT if an exception occurs. If you omit DEFAULT, undefined is returned.

addDirectory DIRECTORY

Adds files from DIRECTORY to the database.

largestWdl

Returns the maximum number of pieces for which WDL probes can be done. A value of 0 means that no WDL tables have been found.

largestDtz

Returns the maximum number of pieces for which WDL probes can be done. A value of 0 means that no DTZ tables have been found.

largest

Returns the maximum of largestWdl and largestDtz.

COPYRIGHT

Copyright (C) 2021-2025 Guido Flohr <guido.flohr@cantanea.com>.

SEE ALSO

Chess::Plisco(3pm), fathom(1), perl(1)

cpanm Chess::Plisco

perl -MCPAN -e shell
install Chess::Plisco