chesstb: support frozen opposing-pawn-pair ('p') tables in the prober

Mirror the generator/probe additions for the lowercase-'p' material: an
opposing pawn pair (white below black on one file) indexed jointly so a
large table shrinks to a partial 'p' variant.

- PairGroup: the 120-placement same-file opposing enumeration, with
  index_of / find_canonical matching src/egtb/pair_group.h exactly (the
  on-disk pawn-slice ids depend on the enumeration order).
- PawnSliceManager: 3-way pair x free_white x free_black product.
- PositionIndexConfig: force file-mirror symmetry when a pair is present,
  collect the pair pawns even with no free-pawn class, and split the
  canonical opposing pair out of the all-pawns placement at index time.
- PieceConfig: has_pair flag; min_key stays pair-stripped (on-disk header),
  cache_key adds the pair bit so a 'p'-material and its free-pieces twin
  (e.g. KQpKp vs KQK) don't collide in the in-memory caches; name() emits
  'p' on both sides (KQpKp).
- probe(): prefer the 'p' table for an opposing-pair board when it is on
  disk, else fall back to the full material.

Cross-checked 500 random KQpKp/KpKp positions against the C++ probe_fen
(WDL + DTC) with zero mismatches.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: noobpwnftw

chess/chesstb.py

@@ -159,11 +159,15 @@ def _composition_key(pieces: List[Tuple[int, int]], color: int) -> List[int]:
 
 
 class PieceConfig:
-    """Canonical material config. `pieces` is a list of (cpp_color, type)."""
+    """Canonical material config. `pieces` is a list of (cpp_color, type) of the
+    FREE pieces. `has_pair` marks a frozen opposing pawn pair (lowercase 'p'):
+    one white + one black pawn locked on a file, indexed jointly and excluded
+    from `pieces` (mirrors src/chess/piece_config.h)."""
 
-    def __init__(self, pieces: List[Tuple[int, int]]):
+    def __init__(self, pieces: List[Tuple[int, int]], has_pair: bool = False):
         # Determine side ordering by total strength; stronger side -> WHITE.
-        # Input may be in any orientation; we canonicalize.
+        # Input may be in any orientation; we canonicalize. The pair is
+        # strength-neutral (one pawn each side), so it never affects the swap.
         ws = sum(_STRENGTH[t] for c, t in pieces if c == CPP_WHITE)
         bs = sum(_STRENGTH[t] for c, t in pieces if c == CPP_BLACK)
         swap = bs > ws
@@ -174,17 +178,38 @@ def __init__(self, pieces: List[Tuple[int, int]]):
         # sort: white side first then black; within side by type order.
         pieces = sorted(pieces, key=lambda ct: (ct[0], _TYPE_ORDER[ct[1]]))
         self.pieces = pieces
+        self.has_pair = has_pair
         self.base_key = material_key_of(pieces)
         self.mirr_key = material_key_of(
             [(CPP_BLACK if c == CPP_WHITE else CPP_WHITE, t) for c, t in pieces])
 
     @property
     def min_key(self) -> int:
+        # Pair-stripped 30-bit value, as serialized in the on-disk header.
         return min(self.base_key, self.mirr_key)
 
+    @property
+    def cache_key(self) -> int:
+        # In-memory key distinguishing a 'p'-material from its free-pieces twin
+        # (which share min_key). Not for disk; canonical min-keys are < 2^31.
+        return self.min_key | (0x80000000 if self.has_pair else 0)
+
     def name(self) -> str:
+        # The pair contributes one pawn to each side; emit a 'p' at the end of
+        # the white side (before the 2nd king) and another at the very end, e.g.
+        # "KQpKp" -- so a board-derived pair config resolves the right filename.
         letters = {KING: "K", QUEEN: "Q", ROOK: "R", BISHOP: "B", KNIGHT: "N", PAWN: "P"}
-        return "".join(letters[t] for c, t in self.pieces)
+        s = []
+        seen_white_king = False
+        for c, t in self.pieces:
+            if t == KING:
+                if seen_white_king and self.has_pair:
+                    s.append("p")
+                seen_white_king = True
+            s.append(letters[t])
+        if self.has_pair:
+            s.append("p")
+        return "".join(s)
 
     @property
     def num_pieces(self) -> int:
@@ -208,6 +233,29 @@ def piece_config_from_board(board: chess.Board) -> Tuple["PieceConfig", bool]:
     return cfg, mirrored
 
 
+def pair_config_from_board(board: chess.Board) -> Optional[Tuple["PieceConfig", bool]]:
+    """If `board` has an opposing pawn pair, return (frozen-pair PieceConfig,
+    mirrored?); else None. The pair's two pawns are excluded from the config and
+    flagged via has_pair, mirroring src/probe/probe.cpp pair_config_from_position.
+    Used to prefer a 'p' table over the full material when one is on disk."""
+    wp = list(board.pieces(chess.PAWN, WHITE))
+    bp = list(board.pieces(chess.PAWN, BLACK))
+    found = PairGroup.find_canonical(wp, bp)
+    if found is None:
+        return None
+    pw, pb = found
+    pieces = []
+    for sq in range(64):
+        if sq == pw or sq == pb:
+            continue
+        p = board.piece_at(sq)
+        if p:
+            pieces.append((cpp_color(p.color), _PC_TO_CPP[p.piece_type]))
+    cfg = PieceConfig(pieces, has_pair=True)
+    mirrored = material_key_of(pieces) != cfg.base_key
+    return cfg, mirrored
+
+
 # ---------------------------------------------------------------------------
 # Piece_Class enum (src/chess/piece_config.h)
 # ---------------------------------------------------------------------------
@@ -357,46 +405,138 @@ def king_slice_mgr(sym: int) -> KingSliceManager:
 # ---------------------------------------------------------------------------
 # Pawn_Slice_Manager
 # ---------------------------------------------------------------------------
+class PairGroup:
+    """Opposing pawn pair (lowercase 'p'): white pawn on rank r, black on rank s,
+    r < s, same file. Enumeration / index_of / find_canonical must match
+    src/egtb/pair_group.h exactly -- the on-disk pawn-slice ids depend on them.
+    White ranks 2..6, black 3..7: C(6,2)=15 rank pairs x 8 files = 120."""
+
+    def __init__(self) -> None:
+        self.white: List[int] = []
+        self.black: List[int] = []
+        self._inv: Dict[Tuple[int, int], int] = {}
+        for f in range(8):
+            for wr in range(1, 6):          # ranks 2..6
+                for br in range(wr + 1, 7):  # ranks 3..7
+                    w = sq_make(wr, f)
+                    b = sq_make(br, f)
+                    self._inv[(w, b)] = len(self.white)
+                    self.white.append(w)
+                    self.black.append(b)
+
+    @property
+    def table_size(self) -> int:
+        return len(self.white)
+
+    def white_square(self, i: int) -> int:
+        return self.white[i]
+
+    def black_square(self, i: int) -> int:
+        return self.black[i]
+
+    def index_of(self, w: int, b: int) -> int:
+        return self._inv[(w, b)]
+
+    @staticmethod
+    def is_opposing_pair(w: int, b: int) -> bool:
+        return (sq_file(w) == sq_file(b)
+                and sq_rank(w) >= 1 and sq_rank(b) <= 6
+                and sq_rank(w) < sq_rank(b))
+
+    @staticmethod
+    def find_canonical(white_sqs: List[int], black_sqs: List[int]
+                       ) -> Optional[Tuple[int, int]]:
+        """The opposing pair minimal by (file, white_rank, black_rank), or None.
+        Both the generator's prune and this lookup use this one rule."""
+        best: Optional[Tuple[Tuple[int, int, int], int, int]] = None
+        for w in white_sqs:
+            for b in black_sqs:
+                if not PairGroup.is_opposing_pair(w, b):
+                    continue
+                key = (sq_file(w), sq_rank(w), sq_rank(b))
+                if best is None or key < best[0]:
+                    best = (key, w, b)
+        return None if best is None else (best[1], best[2])
+
+    @staticmethod
+    def canonical_pair(white_sqs: List[int], black_sqs: List[int]) -> Tuple[int, int]:
+        """For callers that know an opposing pair is present (indexing a stored
+        pair-table position): the canonical pair, asserting one exists."""
+        found = PairGroup.find_canonical(white_sqs, black_sqs)
+        assert found is not None
+        return found
+
+
 class PawnSliceManager:
-    def __init__(self, white_group: Optional[PieceGroup], black_group: Optional[PieceGroup]):
-        self.has_pawns = white_group is not None or black_group is not None
+    def __init__(self, pair_group: Optional[PairGroup],
+                 white_group: Optional[PieceGroup], black_group: Optional[PieceGroup]):
+        self.pair_group = pair_group
         self.white_group = white_group
         self.black_group = black_group
+        self.has_pawns = (pair_group is not None
+                          or white_group is not None or black_group is not None)
         if not self.has_pawns:
             self.num_slices = 1
+            self.pair_table_size = 1
             self.white_table_size = 1
             self.black_table_size = 1
             self.storage_by_cartesian = [0]
             self.cartesian_by_storage = [0]
             return
+        self.pair_table_size = pair_group.table_size if pair_group else 1
         self.white_table_size = white_group.table_size if white_group else 1
         self.black_table_size = black_group.table_size if black_group else 1
-        n_cart = self.white_table_size * self.black_table_size
+        # Mixed radix: cart = pair_idx + w_idx*pair_size + b_idx*pair_size*white_size.
+        n_cart = self.pair_table_size * self.white_table_size * self.black_table_size
         self.storage_by_cartesian = [-1] * n_cart
         self.cartesian_by_storage = []
         for cart in range(n_cart):
-            w_idx = cart % self.white_table_size
-            b_idx = cart // self.white_table_size
-            w_pl = white_group.squares(w_idx) if white_group else []
-            b_pl = black_group.squares(b_idx) if black_group else []
-            if set(w_pl) & set(b_pl):
+            pair_idx = cart % self.pair_table_size
+            rem = cart // self.pair_table_size
+            w_idx = rem % self.white_table_size
+            b_idx = rem // self.white_table_size
+            sqs: List[int] = []
+            if pair_group:
+                sqs.append(pair_group.white_square(pair_idx))
+                sqs.append(pair_group.black_square(pair_idx))
+            if white_group:
+                sqs.extend(white_group.squares(w_idx))
+            if black_group:
+                sqs.extend(black_group.squares(b_idx))
+            if len(set(sqs)) != len(sqs):
                 continue
+            if pair_group:
+                pair_w = pair_group.white_square(pair_idx)
+                pair_b = pair_group.black_square(pair_idx)
+                wsqs = [pair_w]
+                bsqs = [pair_b]
+                if white_group:
+                    wsqs.extend(white_group.squares(w_idx))
+                if black_group:
+                    bsqs.extend(black_group.squares(b_idx))
+                cw, cb = PairGroup.canonical_pair(wsqs, bsqs)
+                if cw != pair_w or cb != pair_b:
+                    continue
             self.storage_by_cartesian[cart] = len(self.cartesian_by_storage)
             self.cartesian_by_storage.append(cart)
         self.num_slices = len(self.cartesian_by_storage)
 
-    def compose(self, w_idx: int, b_idx: int) -> int:
+    def compose(self, pair_idx: int, w_idx: int, b_idx: int) -> int:
         if not self.has_pawns:
             return 0
-        cart = w_idx + b_idx * self.white_table_size
+        cart = (pair_idx
+                + w_idx * self.pair_table_size
+                + b_idx * self.pair_table_size * self.white_table_size)
         return self.storage_by_cartesian[cart]
 
-    def lookup_from_squares(self, white_pawn_sqs: List[int], black_pawn_sqs: List[int]) -> int:
+    def lookup_from_squares(self, pair_w: int, pair_b: int,
+                            white_pawn_sqs: List[int], black_pawn_sqs: List[int]) -> int:
         if not self.has_pawns:
             return 0
+        pair_idx = self.pair_group.index_of(pair_w, pair_b) if self.pair_group else 0
         w_idx = self.white_group.compound_index(white_pawn_sqs) if self.white_group else 0
         b_idx = self.black_group.compound_index(black_pawn_sqs) if self.black_group else 0
-        return self.compose(w_idx, b_idx)
+        return self.compose(pair_idx, w_idx, b_idx)
 
 
 # ---------------------------------------------------------------------------
@@ -432,7 +572,10 @@ def __init__(self, cfg: PieceConfig):
         counts: Dict[Tuple[int, int], int] = {}
         for c, t in cfg.pieces:
             counts[(c, t)] = counts.get((c, t), 0) + 1
-        has_pawns = counts.get((CPP_WHITE, PAWN), 0) > 0 or counts.get((CPP_BLACK, PAWN), 0) > 0
+        # A frozen pair is two pawns on the board, so it breaks symmetry to
+        # file-mirror like any pawn even with no free pawns.
+        has_pawns = (counts.get((CPP_WHITE, PAWN), 0) > 0
+                     or counts.get((CPP_BLACK, PAWN), 0) > 0 or cfg.has_pair)
         self.sym = SYM_FILE_MIRROR if has_pawns else SYM_DIHEDRAL_8
         self.ksm = king_slice_mgr(self.sym)
 
@@ -446,10 +589,12 @@ def __init__(self, cfg: PieceConfig):
                 pcl = make_piece_class(c, t)
                 self.groups[pcl] = PieceGroup(t, n)
 
+        self.pair_group = PairGroup() if cfg.has_pair else None
         if has_pawns:
-            self.psm = PawnSliceManager(self.groups.get(WHITE_PAWNS), self.groups.get(BLACK_PAWNS))
+            self.psm = PawnSliceManager(self.pair_group,
+                                        self.groups.get(WHITE_PAWNS), self.groups.get(BLACK_PAWNS))
         else:
-            self.psm = PawnSliceManager(None, None)
+            self.psm = PawnSliceManager(None, None, None)
         self.num_pawn_slices = self.psm.num_slices
 
         # populated non-pawn classes in ascending class-id order; native weights.
@@ -489,10 +634,12 @@ def _placements_from_board(self, board: chess.Board) -> Dict[int, List[int]]:
             cc, tt = class_to_piece(c)
             color = WHITE if cc == CPP_WHITE else BLACK
             pl[c] = list(board.pieces(_CPP_TO_PC[tt], color))
+        # Collect pawns when a free-pawn class is populated OR a frozen pair adds
+        # pawns with no free-pawn class (e.g. KpKp). The pair members are folded
+        # in here and split out by find_canonical at index time.
         for c in (WHITE_PAWNS, BLACK_PAWNS):
-            if c in self.groups:
-                cc, tt = class_to_piece(c)
-                color = WHITE if cc == CPP_WHITE else BLACK
+            if c in self.groups or self.pair_group is not None:
+                color = WHITE if c == WHITE_PAWNS else BLACK
                 pl[c] = list(board.pieces(chess.PAWN, color))
         return pl
 
@@ -529,7 +676,16 @@ def board_index(self, board: chess.Board, order: List[int], radix: List[int]) ->
             return None
         pawn_slice = 0
         if self.psm.has_pawns:
-            pawn_slice = self.psm.lookup_from_squares(pl[WHITE_PAWNS], pl[BLACK_PAWNS])
+            w_pl, b_pl = pl[WHITE_PAWNS], pl[BLACK_PAWNS]
+            if self.pair_group is not None:
+                # Identify the pair (canonical opposing pair); the rest are free.
+                pw, pb = PairGroup.canonical_pair(w_pl, b_pl)
+                free_w = [s for s in w_pl if s != pw]
+                free_b = [s for s in b_pl if s != pb]
+            else:
+                pw = pb = -1
+                free_w, free_b = w_pl, b_pl
+            pawn_slice = self.psm.lookup_from_squares(pw, pb, free_w, free_b)
         within_idx = {c: self.groups[c].compound_index(pl[c]) for c in self.populated}
         within = 0
         w = 1
@@ -544,7 +700,7 @@ def board_index(self, board: chess.Board, order: List[int], radix: List[int]) ->
 
 
 def position_index_config(cfg: PieceConfig) -> PositionIndexConfig:
-    k = cfg.base_key
+    k = cfg.cache_key
     if k not in _INDEX_CFG_CACHE:
         _INDEX_CFG_CACHE[k] = PositionIndexConfig(cfg)
     return _INDEX_CFG_CACHE[k]
@@ -1650,29 +1806,28 @@ def _find(self, kind: str, name: str, ext: str) -> Optional[str]:
         return None
 
     def _open_wdl(self, cfg: PieceConfig) -> Optional[WDLFile]:
-        k = cfg.min_key
+        k = cfg.cache_key
         if k not in self._wdl_cache:
             p = self._find("wdl", cfg.name(), WDLFile.EXT)
             self._wdl_cache[k] = WDLFile(cfg, p, self._block_cache) if p else None
         return self._wdl_cache[k]
 
     def _open_dtc(self, cfg: PieceConfig) -> Optional[DTCFile]:
-        k = cfg.min_key
+        k = cfg.cache_key
         if k not in self._dtc_cache:
             p = self._find("dtc", cfg.name(), DTCFile.EXT)
             self._dtc_cache[k] = DTCFile(cfg, p, self._block_cache) if p else None
         return self._dtc_cache[k]
 
     def _open_dtm50(self, cfg: PieceConfig) -> Optional[DTM50File]:
-        k = cfg.min_key
+        k = cfg.cache_key
         if k not in self._dtm50_cache:
             p = self._find("dtm50", cfg.name(), DTM50File.EXT)
             self._dtm50_cache[k] = DTM50File(cfg, p, self._block_cache) if p else None
         return self._dtm50_cache[k]
 
     def _has_any_table(self, cfg: PieceConfig) -> bool:
-        return (self._open_wdl(cfg) is not None or self._open_dtc(cfg) is not None
-                or self._open_dtm50(cfg) is not None)
+        return self._open_wdl(cfg) is not None
 
     # --- child construction for the derive / overlay paths ---
     def _make_child(self, parent: chess.Board, move: chess.Move
@@ -2020,7 +2175,15 @@ def probe(self, board: chess.Board, rule50: int = 0) -> Optional[ProbeResult]:
         """Full probe of `board`. `rule50` (the halfmove clock) selects the
         DTM50 layer. Returns a :class:`ProbeResult`, or ``None`` if no table is
         available for the material."""
-        cfg, mirrored = piece_config_from_board(board)
+        # Prefer a frozen-pair table: if the board has an opposing pawn pair and
+        # that 'p' table is on disk, route there; else fall back to the full
+        # material. The pair table is partial and a position has the same value
+        # in either, so preferring the pair table when present is safe.
+        paired = pair_config_from_board(board)
+        if paired is not None and self._has_any_table(paired[0]):
+            cfg, mirrored = paired
+        else:
+            cfg, mirrored = piece_config_from_board(board)
         if mirrored:
             cboard = mirror_for_canonical(board)
             ep = sq_rank_mirror(board.ep_square) if board.ep_square is not None else None