mirror of
https://github.com/TheRealOwenRees/chess-endgame-trainer.git
synced 2026-11-18 03:32:06 +00:00
Motifs describe the kind of problem, independent of the material family. One local tablebase probe returns the root WDL, the DTZ and every legal move with its own WDL, so each motif is proved without a search or a remote lookup. - only move: more than one legal move and exactly one preserves the 50-move-aware result, for wins and draws. - underpromotion: a preserving underpromotion exists while no preserving queen promotion does. - 50-move draw: cursed/blessed WDL, or a win whose DTZ exceeds the remaining halfmove budget. Motif links are recorded as derived and refreshed as a whole, scoped to the motif themes, so material, curated and community links survive. Loss endgames are skipped because only-move is undefined there. Stalemate is deferred: a stored endgame cannot itself be terminal, so it can only describe a line and needs a definition before it becomes a predicate. Release helpers run the derivation without starting the web application, so `bin/chesstrainer eval` works on the server. Closes #188
182 lines
5.9 KiB
Elixir
182 lines
5.9 KiB
Elixir
defmodule Chesstrainer.Endgames.Tablebase.Backend.Fathom do
|
|
@moduledoc """
|
|
Local Syzygy backend powered by the Fathom NIF.
|
|
|
|
Handles positions with up to five pieces. Falls back to the remote backend
|
|
(Lichess by default) when the tablebases are not configured, the probe fails,
|
|
or Fathom cannot answer the position, so play never blocks.
|
|
|
|
The backend is overridable for tests via
|
|
`config :chesstrainer, :tablebase_fallback, Module`.
|
|
"""
|
|
|
|
@behaviour Chesstrainer.Endgames.Tablebase.Backend
|
|
|
|
alias Chesstrainer.Endgames.Tablebase
|
|
alias Chesstrainer.Endgames.Tablebase.Backend.Lichess
|
|
alias Chesstrainer.Endgames.Tablebase.Fathom, as: Nif
|
|
alias Chesstrainer.Endgames.Tablebase.Local
|
|
alias Chesstrainer.Endgames.Tablebase.Move
|
|
alias Chesstrainer.Endgames.Tablebase.San
|
|
alias Chesstrainer.FEN
|
|
|
|
@impl true
|
|
def probe(fen) do
|
|
with {:ok, _largest} <- Local.check(),
|
|
{:ok, {root, moves}} <- Nif.probe(fen) do
|
|
case root do
|
|
:failed -> fallback(fen)
|
|
_ -> {:ok, to_tablebase(fen, root, moves)}
|
|
end
|
|
else
|
|
_ -> fallback(fen)
|
|
end
|
|
end
|
|
|
|
@doc """
|
|
Probes the local tablebase without the remote fallback and returns only the
|
|
position's result.
|
|
|
|
Used by the admin bulk importer, which must never import a result from
|
|
Lichess. The result is from the side-to-move's perspective, matching the
|
|
`category` on `Chesstrainer.Endgames.Tablebase`.
|
|
|
|
Returns `{:error, :terminal}` for checkmate, stalemate, and positions with no
|
|
legal moves, because they cannot be played as puzzles.
|
|
"""
|
|
@spec probe_result_local(String.t()) ::
|
|
{:ok, Tablebase.result()}
|
|
| {:error, :not_configured | :illegal | :terminal | :unsupported}
|
|
def probe_result_local(fen) do
|
|
with {:ok, largest} <- Local.check(),
|
|
pieces when is_integer(pieces) <- FEN.piece_count(fen),
|
|
true <- pieces <= largest || {:error, :unsupported},
|
|
{:ok, {root, moves}} <- Nif.probe(fen) do
|
|
case root do
|
|
:failed ->
|
|
{:error, :illegal}
|
|
|
|
:checkmate ->
|
|
{:error, :terminal}
|
|
|
|
:stalemate ->
|
|
{:error, :terminal}
|
|
|
|
{wdl, _from, _to, _promotes, _ep, _dtz} ->
|
|
if moves == [] do
|
|
{:error, :terminal}
|
|
else
|
|
case Tablebase.normalize_wdl(wdl) do
|
|
:unknown -> {:error, :unsupported}
|
|
category -> {:ok, category}
|
|
end
|
|
end
|
|
end
|
|
else
|
|
{:error, :not_configured} = error -> error
|
|
{:error, :unsupported} = error -> error
|
|
{:error, _reason} -> {:error, :unsupported}
|
|
nil -> {:error, :unsupported}
|
|
end
|
|
end
|
|
|
|
@doc """
|
|
Probes the local tablebase and returns the raw root outcome and move list.
|
|
|
|
Unlike `probe_result_local/1`, this keeps the per-move tuples and the raw WDL
|
|
atom, including `:cursed_win` and `:blessed_loss`, which the motif derivation
|
|
needs. It never falls back to the remote backend or consults the cache.
|
|
|
|
Returns `{:error, :unsupported}` when the local files cannot answer the
|
|
position, including a partial tablebase set where Fathom reports `:failed`.
|
|
"""
|
|
@spec probe_local_detail(String.t()) ::
|
|
{:ok, %{wdl: atom(), dtz: integer(), moves: [tuple()]}}
|
|
| {:error, :not_configured | :terminal | :unsupported}
|
|
def probe_local_detail(fen) do
|
|
with {:ok, largest} <- Local.check(),
|
|
pieces when is_integer(pieces) <- FEN.piece_count(fen),
|
|
true <- pieces <= largest || {:error, :unsupported},
|
|
{:ok, {root, moves}} <- Nif.probe(fen) do
|
|
case root do
|
|
:failed -> {:error, :unsupported}
|
|
:checkmate -> {:error, :terminal}
|
|
:stalemate -> {:error, :terminal}
|
|
{wdl, _from, _to, _promotes, _ep, dtz} -> {:ok, %{wdl: wdl, dtz: dtz, moves: moves}}
|
|
end
|
|
else
|
|
{:error, :not_configured} = error -> error
|
|
{:error, :unsupported} = error -> error
|
|
{:error, _reason} -> {:error, :unsupported}
|
|
nil -> {:error, :unsupported}
|
|
end
|
|
end
|
|
|
|
defp fallback(fen) do
|
|
(Application.get_env(:chesstrainer, :tablebase_fallback) || Lichess).probe(fen)
|
|
end
|
|
|
|
defp to_tablebase(_fen, :checkmate, _moves) do
|
|
%Tablebase{category: :loss, checkmate: true, moves: []}
|
|
end
|
|
|
|
defp to_tablebase(_fen, :stalemate, _moves) do
|
|
%Tablebase{category: :draw, checkmate: false, moves: []}
|
|
end
|
|
|
|
defp to_tablebase(fen, {wdl, _from, _to, _promotes, _ep, _dtz}, moves) do
|
|
%Tablebase{
|
|
category: Tablebase.normalize_wdl(wdl),
|
|
checkmate: false,
|
|
moves: fen |> map_moves(moves) |> sort_moves()
|
|
}
|
|
end
|
|
|
|
defp map_moves(fen, moves) do
|
|
Enum.map(moves, fn {wdl, from, to, promotes, _ep, dtz} ->
|
|
uci = uci(from, to, promotes)
|
|
|
|
%Move{
|
|
category: move_category(wdl),
|
|
dtz: dtz,
|
|
uci: uci,
|
|
san: San.for_uci(fen, uci)
|
|
}
|
|
end)
|
|
end
|
|
|
|
# Best move first: highest mover outcome, then sharpest DTZ (lowest for a
|
|
# mover who is winning, highest for a mover who is losing).
|
|
defp sort_moves(moves) do
|
|
Enum.sort_by(moves, fn %Move{category: category, dtz: dtz} ->
|
|
rank = mover_rank(Tablebase.flip(category))
|
|
{-rank, if(rank == 0, do: -(dtz || 0), else: dtz || 0)}
|
|
end)
|
|
end
|
|
|
|
# Fathom reports a move's WDL from the mover's perspective; the trainer stores
|
|
# the resulting position's category (the opponent's perspective).
|
|
defp move_category(wdl), do: Tablebase.flip(Tablebase.normalize_wdl(wdl))
|
|
|
|
defp mover_rank(:win), do: 2
|
|
defp mover_rank(:draw), do: 1
|
|
defp mover_rank(:loss), do: 0
|
|
defp mover_rank(_), do: -1
|
|
|
|
defp uci(from, to, promotes) do
|
|
square(from) <> square(to) <> promotion_suffix(promotes)
|
|
end
|
|
|
|
defp square(square) do
|
|
file = rem(square, 8)
|
|
rank = div(square, 8)
|
|
<<?a + file>> <> Integer.to_string(rank + 1)
|
|
end
|
|
|
|
defp promotion_suffix(1), do: "q"
|
|
defp promotion_suffix(2), do: "r"
|
|
defp promotion_suffix(3), do: "b"
|
|
defp promotion_suffix(4), do: "n"
|
|
defp promotion_suffix(_), do: ""
|
|
end
|