from __future__ import annotations import ctypes import os from dataclasses import dataclass from pathlib import Path from typing import Any, Optional import numpy as np _PROJECT_ROOT = Path(__file__).resolve().parents[2] _DEFAULT_DLL_PATH = _PROJECT_ROOT / "bin" / "egaroucid_bridge.dll" _DEFAULT_RESOURCES_DIR = _PROJECT_ROOT / "resources" class DualistEvalOutput(ctypes.Structure): """Exact mirror of #pragma pack(push, 1) DualistEvalOutput in dualist_bridge.hpp.""" _pack_ = 1 _fields_ = [ ("best_move", ctypes.c_int8), ("root_value", ctypes.c_float), ("policy_q_values", ctypes.c_float * 65), ("is_exact", ctypes.c_uint8), ("search_level", ctypes.c_uint8), ("probability", ctypes.c_uint8), ("legal_move_count", ctypes.c_uint8), ("nodes_searched", ctypes.c_uint64), ] @dataclass(frozen=True) class OracleEvaluation: best_move: int root_value: float policy_q_values: np.ndarray # shape (65,), float32 is_exact: bool search_level: int probability: int legal_move_count: int nodes_searched: int class FeatureScratchBuffers: """Reusable pre-allocated C-contiguous NumPy buffers for zero-copy feature extraction.""" def __init__(self, batch_size: int) -> None: self.batch_size = int(batch_size) self.players = np.empty(self.batch_size, dtype=np.uint64) self.opponents = np.empty(self.batch_size, dtype=np.uint64) self.spatial = np.empty((self.batch_size, 16, 8, 8), dtype=np.float32) self.scalars = np.empty((self.batch_size, 32), dtype=np.float32) self.legal_mask = np.empty((self.batch_size, 65), dtype=np.uint8) def ptrs(self) -> tuple[int, int, int, int, int]: return ( self.players.ctypes.data, self.opponents.ctypes.data, self.spatial.ctypes.data, self.scalars.ctypes.data, self.legal_mask.ctypes.data, ) class EgaroucidBridge: """Thread-safe zero-copy ctypes wrapper around bin/egaroucid_bridge.dll.""" def __init__(self, dll_path: Optional[Path | str] = None) -> None: if dll_path is not None: resolved_dll = Path(dll_path).resolve() else: local_dll = Path(__file__).resolve().parent / "egaroucid_bridge.dll" resolved_dll = _DEFAULT_DLL_PATH.resolve() if _DEFAULT_DLL_PATH.exists() else local_dll.resolve() if not resolved_dll.exists(): raise FileNotFoundError(f"Saknar C++20-bryggan: {resolved_dll}") if os.name == "nt": llvm_bin = _PROJECT_ROOT / "third_party" / "llvm-mingw" / "bin" if llvm_bin.exists(): os.add_dll_directory(str(llvm_bin)) os.add_dll_directory(str(resolved_dll.parent)) # ctypes.CDLL releases the Python GIL around C calls by default. self._lib = ctypes.CDLL(str(resolved_dll)) self._bind_signatures() def _bind_signatures(self) -> None: u64_p = ctypes.POINTER(ctypes.c_uint64) f32_p = ctypes.POINTER(ctypes.c_float) u8_p = ctypes.POINTER(ctypes.c_uint8) i32_p = ctypes.POINTER(ctypes.c_int) self._lib.dualist_init_engine.argtypes = [ ctypes.c_char_p, ctypes.c_int, ctypes.c_int, ctypes.c_int, ] self._lib.dualist_init_engine.restype = ctypes.c_int self._lib.dualist_shutdown_engine.argtypes = [] self._lib.dualist_shutdown_engine.restype = None self._lib.dualist_is_initialized.argtypes = [] self._lib.dualist_is_initialized.restype = ctypes.c_int self._lib.dualist_extract_features_batch.argtypes = [ ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ] self._lib.dualist_extract_features_batch.restype = None self._lib.dualist_oracle_evaluate.argtypes = [ ctypes.c_uint64, ctypes.c_uint64, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.POINTER(DualistEvalOutput), ] self._lib.dualist_oracle_evaluate.restype = ctypes.c_int self._lib.dualist_mid_evaluate.argtypes = [ctypes.c_uint64, ctypes.c_uint64] self._lib.dualist_mid_evaluate.restype = ctypes.c_int self._lib.dualist_perft.argtypes = [ ctypes.c_uint64, ctypes.c_uint64, ctypes.c_int, ctypes.c_int, ] self._lib.dualist_perft.restype = ctypes.c_uint64 self._lib.dualist_apply_move.argtypes = [ ctypes.c_uint64, ctypes.c_uint64, ctypes.c_int, u64_p, u64_p, ] self._lib.dualist_apply_move.restype = ctypes.c_int self._lib.dualist_is_game_over.argtypes = [ ctypes.c_uint64, ctypes.c_uint64, i32_p, ] self._lib.dualist_is_game_over.restype = ctypes.c_int self._lib.dualist_book_lookup.argtypes = [ ctypes.c_uint64, ctypes.c_uint64, i32_p, i32_p, i32_p, ] self._lib.dualist_book_lookup.restype = ctypes.c_int self._lib.dualist_solve_endgame_exact.argtypes = [ ctypes.c_uint64, ctypes.c_uint64, ctypes.c_void_p, ctypes.c_int, ctypes.POINTER(DualistEvalOutput), ] self._lib.dualist_solve_endgame_exact.restype = ctypes.c_int self._lib.dualist_e2_init_zero.argtypes = [] self._lib.dualist_e2_init_zero.restype = ctypes.c_int self._lib.dualist_e2_train_batch.argtypes = [ ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int, ctypes.c_float, ctypes.c_float, ctypes.c_int, ctypes.POINTER(ctypes.c_double), ] self._lib.dualist_e2_train_batch.restype = ctypes.c_int self._lib.dualist_e2_smooth_phases.argtypes = [ctypes.c_float] self._lib.dualist_e2_smooth_phases.restype = ctypes.c_int self._lib.dualist_e2_sync_eval.argtypes = [] self._lib.dualist_e2_sync_eval.restype = ctypes.c_int self._lib.dualist_e2_eval_batch.argtypes = [ ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int, f32_p, ] self._lib.dualist_e2_eval_batch.restype = ctypes.c_int self._lib.dualist_e2_save_egev2.argtypes = [ctypes.c_char_p] self._lib.dualist_e2_save_egev2.restype = ctypes.c_int self._lib.dualist_e2_load_egev2.argtypes = [ctypes.c_char_p] self._lib.dualist_e2_load_egev2.restype = ctypes.c_int self._lib.dualist_e2_search.argtypes = [ ctypes.c_uint64, ctypes.c_uint64, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_void_p, ctypes.POINTER(DualistEvalOutput), ] self._lib.dualist_e2_search.restype = ctypes.c_int @property def is_initialized(self) -> bool: return bool(self._lib.dualist_is_initialized()) def init_engine( self, resources_dir: Optional[Path | str] = None, hash_level: int = 27, num_threads: int = 12, show_log: bool = False, ) -> None: res_path = Path(resources_dir) if resources_dir is not None else _DEFAULT_RESOURCES_DIR rc = self._lib.dualist_init_engine( str(res_path).encode("utf-8"), int(hash_level), int(num_threads), 1 if show_log else 0, ) if rc != 0: raise RuntimeError(f"dualist_init_engine misslyckades med felkod {rc} ({res_path})") def shutdown(self) -> None: self._lib.dualist_shutdown_engine() def extract_features_into( self, players: np.ndarray, opponents: np.ndarray, out_spatial: np.ndarray, out_scalars: np.ndarray, out_legal_mask: np.ndarray, ) -> None: """Zero-copy feature extraction writing directly into pre-allocated C-contiguous buffers.""" n = int(players.shape[0]) if n <= 0: return if not ( players.flags["C_CONTIGUOUS"] and opponents.flags["C_CONTIGUOUS"] and out_spatial.flags["C_CONTIGUOUS"] and out_scalars.flags["C_CONTIGUOUS"] and out_legal_mask.flags["C_CONTIGUOUS"] ): raise ValueError("Alla arrayer till extract_features_into maste vara C-contiguous.") if ( players.dtype != np.uint64 or opponents.dtype != np.uint64 or out_spatial.dtype != np.float32 or out_scalars.dtype != np.float32 or out_legal_mask.dtype != np.uint8 ): raise ValueError("Fel dtype i buffertar till extract_features_into.") if ( players.shape != (n,) or opponents.shape != (n,) or out_spatial.shape != (n, 16, 8, 8) or out_scalars.shape != (n, 32) or out_legal_mask.shape != (n, 65) ): raise ValueError("Ogiltig bufferform for extract_features_into.") self._lib.dualist_extract_features_batch( players.ctypes.data, opponents.ctypes.data, n, out_spatial.ctypes.data, out_scalars.ctypes.data, out_legal_mask.ctypes.data, ) def extract_features_batch( self, players: np.ndarray, opponents: np.ndarray, ) -> tuple[np.ndarray, np.ndarray, np.ndarray]: p_arr = np.ascontiguousarray(players, dtype=np.uint64) o_arr = np.ascontiguousarray(opponents, dtype=np.uint64) n = int(p_arr.shape[0]) spatial = np.empty((n, 16, 8, 8), dtype=np.float32) scalars = np.empty((n, 32), dtype=np.float32) legal_mask = np.empty((n, 65), dtype=np.uint8) self.extract_features_into(p_arr, o_arr, spatial, scalars, legal_mask) return spatial, scalars, legal_mask def oracle_evaluate( self, player: int, opponent: int, level: int = 11, use_book: bool = True, eval_all_moves: bool = True, ) -> OracleEvaluation: out = DualistEvalOutput() rc = self._lib.dualist_oracle_evaluate( int(player), int(opponent), int(level), 1 if use_book else 0, 1 if eval_all_moves else 0, ctypes.byref(out), ) if rc != 0: raise RuntimeError(f"dualist_oracle_evaluate misslyckades med felkod {rc}") q_vals = np.ctypeslib.as_array(out.policy_q_values).copy() return OracleEvaluation( best_move=int(out.best_move), root_value=float(out.root_value), policy_q_values=q_vals, is_exact=bool(out.is_exact), search_level=int(out.search_level), probability=int(out.probability), legal_move_count=int(out.legal_move_count), nodes_searched=int(out.nodes_searched), ) def mid_evaluate(self, player: int, opponent: int) -> int: return int(self._lib.dualist_mid_evaluate(int(player), int(opponent))) def perft(self, player: int, opponent: int, depth: int, count_pass_as_move: bool = True) -> int: return int( self._lib.dualist_perft( int(player), int(opponent), int(depth), 1 if count_pass_as_move else 0, ) ) def apply_move(self, player: int, opponent: int, public_move: int) -> tuple[int, int]: out_p = ctypes.c_uint64(0) out_o = ctypes.c_uint64(0) rc = self._lib.dualist_apply_move( int(player), int(opponent), int(public_move), ctypes.byref(out_p), ctypes.byref(out_o), ) if rc != 0: raise ValueError(f"Olagligt drag {public_move} for ({player:#x}, {opponent:#x})") return int(out_p.value), int(out_o.value) def is_game_over(self, player: int, opponent: int) -> tuple[bool, int]: score = ctypes.c_int(0) ended = self._lib.dualist_is_game_over(int(player), int(opponent), ctypes.byref(score)) return bool(ended), int(score.value) def book_lookup(self, player: int, opponent: int) -> list[tuple[int, int]]: moves = (ctypes.c_int * 65)() values = (ctypes.c_int * 65)() count = ctypes.c_int(0) rc = self._lib.dualist_book_lookup(int(player), int(opponent), moves, values, ctypes.byref(count)) if rc < 0: raise RuntimeError(f"dualist_book_lookup misslyckades med felkod {rc}") return [(int(moves[i]), int(values[i])) for i in range(int(count.value))] def solve_endgame_exact( self, player: int, opponent: int, root_priors_65: Optional[np.ndarray] = None, eval_all_moves: bool = False, ) -> OracleEvaluation: """Pure bitboard NegaScout exact endgame solver (zero eval.egev2 / book).""" out = DualistEvalOutput() priors_ptr: Any = None priors_arr: Optional[np.ndarray] = None if root_priors_65 is not None: priors_arr = np.ascontiguousarray(root_priors_65, dtype=np.float32) if priors_arr.shape != (65,): raise ValueError("root_priors_65 maste ha formen (65,)") priors_ptr = priors_arr.ctypes.data rc = self._lib.dualist_solve_endgame_exact( int(player), int(opponent), priors_ptr, 1 if eval_all_moves else 0, ctypes.byref(out), ) if rc != 0: raise RuntimeError(f"dualist_solve_endgame_exact misslyckades med felkod {rc}") q_vals = np.ctypeslib.as_array(out.policy_q_values).copy() return OracleEvaluation( best_move=int(out.best_move), root_value=float(out.root_value), policy_q_values=q_vals, is_exact=bool(out.is_exact), search_level=int(out.search_level), probability=int(out.probability), legal_move_count=int(out.legal_move_count), nodes_searched=int(out.nodes_searched), ) def e2_init_zero(self) -> None: rc = self._lib.dualist_e2_init_zero() if rc != 0: raise RuntimeError(f"dualist_e2_init_zero misslyckades ({rc})") def e2_train_batch( self, players: np.ndarray, opponents: np.ndarray, targets: np.ndarray, sample_weights: Optional[np.ndarray] = None, lr: float = 0.08, l2_decay: float = 1e-5, augment_mirror: bool = True, ) -> float: p_arr = np.ascontiguousarray(players, dtype=np.uint64) o_arr = np.ascontiguousarray(opponents, dtype=np.uint64) t_arr = np.ascontiguousarray(targets, dtype=np.float32) if p_arr.ndim != 1 or o_arr.shape != p_arr.shape or t_arr.shape != p_arr.shape: raise ValueError( f"players, opponents och targets maste ha samma 1D-form: " f"{p_arr.shape}, {o_arr.shape}, {t_arr.shape}" ) n = int(p_arr.shape[0]) if n == 0: return 0.0 w_ptr: Any = None w_arr: Optional[np.ndarray] = None if sample_weights is not None: w_arr = np.ascontiguousarray(sample_weights, dtype=np.float32) if w_arr.shape != p_arr.shape: raise ValueError(f"sample_weights maste ha form {p_arr.shape}, fick {w_arr.shape}") w_ptr = w_arr.ctypes.data mae = ctypes.c_double(0.0) rc = self._lib.dualist_e2_train_batch( p_arr.ctypes.data, o_arr.ctypes.data, t_arr.ctypes.data, w_ptr, n, float(lr), float(l2_decay), 1 if augment_mirror else 0, ctypes.byref(mae), ) if rc != 0: raise RuntimeError(f"dualist_e2_train_batch misslyckades ({rc})") return float(mae.value) def e2_smooth_phases(self, neighbor_alpha: float = 0.04) -> None: rc = self._lib.dualist_e2_smooth_phases(float(neighbor_alpha)) if rc != 0: raise RuntimeError(f"dualist_e2_smooth_phases misslyckades ({rc})") def e2_sync_eval(self) -> None: rc = self._lib.dualist_e2_sync_eval() if rc != 0: raise RuntimeError(f"dualist_e2_sync_eval misslyckades ({rc})") def e2_eval_batch(self, players: np.ndarray, opponents: np.ndarray) -> np.ndarray: p_arr = np.ascontiguousarray(players, dtype=np.uint64) o_arr = np.ascontiguousarray(opponents, dtype=np.uint64) if p_arr.ndim != 1 or o_arr.shape != p_arr.shape: raise ValueError(f"players och opponents maste ha samma 1D-form: {p_arr.shape}, {o_arr.shape}") n = int(p_arr.shape[0]) out = np.empty(n, dtype=np.float32) if n == 0: return out rc = self._lib.dualist_e2_eval_batch( p_arr.ctypes.data, o_arr.ctypes.data, n, out.ctypes.data_as(ctypes.POINTER(ctypes.c_float)), ) if rc != 0: raise RuntimeError(f"dualist_e2_eval_batch misslyckades ({rc})") return out def e2_save_egev2(self, filepath: Path | str) -> None: p = Path(filepath) p.parent.mkdir(parents=True, exist_ok=True) rc = self._lib.dualist_e2_save_egev2(str(p).encode("utf-8")) if rc != 0: raise RuntimeError(f"dualist_e2_save_egev2 misslyckades ({rc})") def e2_load_egev2(self, filepath: Path | str) -> None: rc = self._lib.dualist_e2_load_egev2(str(filepath).encode("utf-8")) if rc != 0: raise RuntimeError(f"dualist_e2_load_egev2 misslyckades ({rc})") def e2_search( self, player: int, opponent: int, mid_depth: int = 11, endgame_empties: int = 21, use_mpc: bool = True, eval_all_moves: bool = False, root_priors_65: Optional[np.ndarray] = None, ) -> OracleEvaluation: """100% Dualist-owned E.2 pattern Iterative NegaScout + MPC + pure exact endgame.""" out = DualistEvalOutput() priors_ptr: Any = None priors_arr: Optional[np.ndarray] = None if root_priors_65 is not None: priors_arr = np.ascontiguousarray(root_priors_65, dtype=np.float32) if priors_arr.shape != (65,): raise ValueError("root_priors_65 maste ha formen (65,)") priors_ptr = priors_arr.ctypes.data rc = self._lib.dualist_e2_search( int(player), int(opponent), int(mid_depth), int(endgame_empties), 1 if use_mpc else 0, 1 if eval_all_moves else 0, priors_ptr, ctypes.byref(out), ) if rc != 0: raise RuntimeError(f"dualist_e2_search misslyckades ({rc})") q_vals = np.ctypeslib.as_array(out.policy_q_values).copy() return OracleEvaluation( best_move=int(out.best_move), root_value=float(out.root_value), policy_q_values=q_vals, is_exact=bool(out.is_exact), search_level=int(out.search_level), probability=int(out.probability), legal_move_count=int(out.legal_move_count), nodes_searched=int(out.nodes_searched), ) # Standard Othello initial board in Egaroucid bitboard convention: # A1=bit63 .. H8=bit0 -> D4(3,3)=bit36 (O/White), E4(3,4)=bit35 (X/Black), # D5(4,3)=bit28 (X/Black), E5(4,4)=bit27 (O/White) INITIAL_BLACK_BB: int = (1 << 35) | (1 << 28) # 0x0000000810000000 INITIAL_WHITE_BB: int = (1 << 36) | (1 << 27) # 0x0000001008000000 def move_to_coord(move: int) -> str: if move == 64: return "ps" if move < 0 or move > 64: return "--" row, col = divmod(move, 8) return f"{chr(ord('A') + col)}{row + 1}" def coord_to_move(coord: str) -> int: s = coord.strip().lower() if s in {"ps", "pass", "pa"}: return 64 if len(s) != 2 or s[0] < "a" or s[0] > "h" or s[1] < "1" or s[1] > "8": raise ValueError(f"Ogiltig koordinat: {coord}") col = ord(s[0]) - ord("a") row = int(s[1]) - 1 return row * 8 + col