Skip to content

Add chess.chesstb: pure-Python prober for chesstb endgame tablebases - #1194

Open
noobpwnftw wants to merge 1 commit into
niklasf:masterfrom
noobpwnftw:add-chesstb-tablebases
Open

Add chess.chesstb: pure-Python prober for chesstb endgame tablebases#1194
noobpwnftw wants to merge 1 commit into
niklasf:masterfrom
noobpwnftw:add-chesstb-tablebases

Conversation

@noobpwnftw

@noobpwnftw noobpwnftw commented Jun 8, 2026

Copy link
Copy Markdown

Add chess.chesstb: pure-Python prober for chesstb endgame tablebases

What this adds

A new module, chess.chesstb, that probes the chesstb endgame
tablebase format directly from chess.Board positions — in the same spirit as
the existing chess.syzygy and chess.gaviota modules.

chesstb ships three table types per material:

Table Extension Answer
WDL .lzw 50-move-rule-aware win/draw/loss with cursed/blessed classes
DTC .lzdtc distance-to-conversion (plies to the next zeroing move)
DTM50 .lzdtm50 one pack giving both the unbounded DTM and the exact 50MR DTM at any halfmove clock

API

import chess, chess.chesstb

with chess.chesstb.open_tablebase("/path/to/chesstb") as tb:
    board = chess.Board("8/8/8/5k2/8/8/1Q6/K7 w - - 0 1")
    tb.probe_wdl(board)        # 2  (+2 win .. -2 loss, like syzygy)
    tb.probe_dtz(board)        # 19 (signed distance-to-conversion)
    tb.probe_dtm(board)        # 19 (signed distance-to-mate, ignoring 50MR)
    tb.probe_dtm50(board)      # (2, 19): rule-true (wdl, plies) at the board's clock

get_wdl / get_dtz / get_dtm are non-raising variants returning a default
(None) when no table is available. probe(board, rule50=0) returns the full
structured result (all fields at once).

Why pure Python

chess.syzygy is pure Python; this follows suit. The module depends only on
python-chess and the standard library:

  • LZMA (DTC / DTM50 blocks) via stdlib lzma with FORMAT_RAW (the C++
    side uses the LZMA SDK with props appended at each block tail).
  • LZ4 (WDL blocks) via a small bundled pure-Python LZ4-block decoder
    (~30 lines) supporting the optional LZ4 dictionary. No new dependency.

The position index (symmetry canonicalization, king/pawn slice managers, the
binomial piece-group ranking, the radix-composed board index and the
index-permutation layout) and the probe orchestration (dropped-frame one-ply
minimax reconstruction for shrunk files, the en-passant overlay, and the DTM50
halfmove-clock layer selection) are faithful re-implementations of the C++
src/probe library. Square numbering already matches python-chess exactly
(a1=0 … h8=63), so boards are consumed directly.

Validation

Every value is validated bit-for-bit against the reference C++ prober
(tests/probe_fen) by enumerating positions and comparing WDL, DTC/dtz, DTM
and DTM50 in lockstep:

  • All 145 shipped ≤5-man materials, ~72k positions at halfmove clock 0 —
    0 mismatches.
  • Layered DTM50 at halfmove clocks 1, 30, 40, 80, 98, 99 across all
    materials (exercising the CONST/SINGLE/DOUBLE/MULTI changepoint state machine,
    the draw-end hint, and recover_mate_at_hmc) — 0 mismatches.
  • Dropped-frame reconstruction: both the symmetric-mirror path (e.g. KRKR)
    and the asymmetric one-ply-minimax derive (109 of 145 materials ship a dropped
    frame) — 0 mismatches.
  • En-passant overlay and color-mirrored material (stronger side is
    Black) — verified against the oracle.
  • The pure-Python LZ4 decoder is cross-checked block-for-block against the
    reference lz4 C library on every shipped WDL table.
  • The standalone .lzdtm table is intentionally not read: DTM is served from
    the .lzdtm50 pack (layer 0), which supersedes it.

A self-contained test_chesstb.py pins representative expected values (no C++
build required) and skips when no tables are present.

@noobpwnftw
noobpwnftw force-pushed the add-chesstb-tablebases branch 7 times, most recently from a252d4c to 228bac6 Compare July 1, 2026 01:08
@noobpwnftw
noobpwnftw force-pushed the add-chesstb-tablebases branch 10 times, most recently from 3edd50e to b0e8430 Compare August 11, 2026 10:10
chesstb tables store WDL, DTC, DTM and DTM50 for endgame material
configurations. This adds a pure-Python reader for the format, shaped like
chess.syzygy and chess.gaviota: open_tablebase() on a directory tree, then
probe() a board for all four values at once, or probe_wdl / probe_dtz /
probe_dtm / probe_dtm50 for one at a time.

The format, as read here: one table per material configuration, split by
side to move and compressed in blocks (LZMA, or LZ4 with an optional
dictionary prefix). Positions are addressed by a combinatorial index over
king symmetry classes and groups of identical pieces. Configurations of
equal strength share a single table, read through a rank-mirrored,
colour-swapped view of the position; one holding an opposing pawn pair may
also ship a smaller frozen-pair ('p') table, which is preferred when
present, and whose index counts only the free pieces. A table may omit one
side to move altogether, in which case its values are recovered by
minimaxing over legal children. En passant is not indexed and is applied as
a virtual-capture overlay at probe time. DTM50 carries a prefix index every
256 positions within a block and layers its values by halfmove clock.

Tables are memory-mapped and decoded a block at a time, with a shared LRU
holding decoded blocks across every open table against one budget.
_TableFile._open_source is the single seam where the transport is decided,
and the three table classes are named as class attributes, so serving
tables from something other than a mapping is three subclasses and a _find.
A Tablebase is safe to share between threads: probes register as readers so
close() can wait for them before unmapping, and table opens are
double-checked under a per-kind lock.

Positions with castling rights are rejected with MissingTableError, as
chess.syzygy and chess.gaviota do for the same input; the tables are built
without them. Positions are assumed legal, as they are on the C++ side.

Includes docs, tests, and seven small table sets (KBK..KRKR) as test data.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@noobpwnftw
noobpwnftw force-pushed the add-chesstb-tablebases branch from b0e8430 to 5898772 Compare August 11, 2026 10:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant