Dualist-Hyper-v2 / bridge_binding.py
brandonlanexyz's picture
Upload Dualist-Hyper-v2 (model.safetensors, E.2 SIMD table, C++20 bridge, benchmarks)
13adc8b verified
Raw History Blame Contribute Delete
20.7 kB
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