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
199 lines
6.2 KiB
Elixir
199 lines
6.2 KiB
Elixir
defmodule Chesstrainer.Endgames.MotifThemes do
|
|
@moduledoc """
|
|
Derives objective motif themes by probing each endgame's position.
|
|
|
|
Motifs describe the kind of problem, independent of the material family: an
|
|
endgame can be a rook endgame and an only-move puzzle at the same time. Every
|
|
motif is proved from the local Syzygy tables — one probe returns the root WDL,
|
|
the DTZ and every legal move with its own WDL — so nothing here is a guess and
|
|
nothing calls the remote backend.
|
|
|
|
Motif links are recorded as `derived` and refreshed as a whole. Material
|
|
families, curated links and community links are untouched because the refresh
|
|
is scoped to the motif themes.
|
|
|
|
Loss endgames are skipped: only-move is undefined when every move loses, and
|
|
the library no longer contains them.
|
|
"""
|
|
|
|
import Ecto.Query, warn: false
|
|
|
|
alias Chesstrainer.Endgames.Endgame
|
|
alias Chesstrainer.Endgames.Tablebase
|
|
alias Chesstrainer.Endgames.Tablebase.Backend.Fathom, as: FathomBackend
|
|
alias Chesstrainer.Repo
|
|
alias Chesstrainer.Themes
|
|
|
|
@motifs [
|
|
only_move: %{
|
|
name: "only move",
|
|
description:
|
|
"Exactly one legal move keeps the result, so the puzzle is about finding the single accurate move."
|
|
},
|
|
underpromotion: %{
|
|
name: "underpromotion",
|
|
description:
|
|
"The result can only be preserved by promoting to a rook, bishop or knight; promoting to a queen does not work."
|
|
},
|
|
fifty_move_draw: %{
|
|
name: "50-move draw",
|
|
description:
|
|
"The result turns on the fifty-move rule: the win needs more moves than the halfmove clock allows, so the defender can claim a draw."
|
|
}
|
|
]
|
|
|
|
@type motif :: :only_move | :underpromotion | :fifty_move_draw
|
|
|
|
@doc "The motif themes, in a stable order."
|
|
def motifs, do: @motifs
|
|
|
|
@doc """
|
|
Returns the motifs for one probed position.
|
|
|
|
`moves` are Fathom move tuples `{wdl, from, to, promotes, ep, dtz}` and carry
|
|
the mover's perspective, so they are compared with the root WDL directly.
|
|
`halfmove_clock` comes from the FEN; the probe itself runs with `rule50 = 0`.
|
|
"""
|
|
@spec motifs_for(atom(), integer() | nil, [tuple()], non_neg_integer()) :: [motif()]
|
|
def motifs_for(wdl, dtz, moves, halfmove_clock) do
|
|
outcome = Tablebase.normalize_wdl(wdl)
|
|
|
|
preserving =
|
|
Enum.filter(moves, fn {move_wdl, _from, _to, _promotes, _ep, _dtz} ->
|
|
Tablebase.normalize_wdl(move_wdl) == outcome
|
|
end)
|
|
|
|
[]
|
|
|> maybe_only_move(outcome, moves, preserving)
|
|
|> maybe_underpromotion(preserving)
|
|
|> maybe_fifty_move(wdl, dtz, halfmove_clock)
|
|
end
|
|
|
|
@doc """
|
|
Creates or corrects the motif themes, keyed by motif.
|
|
|
|
An existing theme with the same name is reused and its kind and description
|
|
are corrected, so a theme seeded as a technique becomes a motif without
|
|
losing its existing links.
|
|
"""
|
|
@spec ensure_themes() :: %{motif() => Chesstrainer.Themes.Theme.t()}
|
|
def ensure_themes do
|
|
Map.new(@motifs, fn {motif, attrs} ->
|
|
{:ok, theme} = Themes.get_or_create(attrs.name, "endgame", kind: :motif)
|
|
{motif, ensure_motif_theme(theme, attrs)}
|
|
end)
|
|
end
|
|
|
|
@doc """
|
|
Refreshes every endgame's derived motif links.
|
|
|
|
Returns the number of links written, the number of endgames skipped because
|
|
the local tables could not answer them, and a count per motif. Re-running is
|
|
idempotent.
|
|
"""
|
|
@spec derive() :: %{
|
|
links: non_neg_integer(),
|
|
skipped: non_neg_integer(),
|
|
by_motif: %{motif() => non_neg_integer()},
|
|
themes: non_neg_integer()
|
|
}
|
|
def derive do
|
|
themes = ensure_themes()
|
|
motif_ids = Enum.map(themes, fn {_motif, theme} -> theme.id end)
|
|
|
|
initial_counts = Map.new(@motifs, fn {motif, _attrs} -> {motif, 0} end)
|
|
|
|
{links, skipped, by_motif} =
|
|
Endgame
|
|
|> where([e], e.result in [:win, :draw])
|
|
|> select([e], {e.id, e.fen})
|
|
|> Repo.all()
|
|
|> Enum.reduce({[], 0, initial_counts}, fn {id, fen}, {links, skipped, counts} ->
|
|
case probe(fen) do
|
|
{:ok, %{wdl: wdl, dtz: dtz, moves: moves}} ->
|
|
motifs = motifs_for(wdl, dtz, moves, halfmove_clock(fen))
|
|
|
|
links =
|
|
Enum.reduce(motifs, links, fn motif, acc ->
|
|
[{id, Map.fetch!(themes, motif).id} | acc]
|
|
end)
|
|
|
|
counts =
|
|
Enum.reduce(motifs, counts, fn motif, acc ->
|
|
Map.update!(acc, motif, &(&1 + 1))
|
|
end)
|
|
|
|
{links, skipped, counts}
|
|
|
|
{:error, _reason} ->
|
|
{links, skipped + 1, counts}
|
|
end
|
|
end)
|
|
|
|
:ok = Themes.replace_theme_links(motif_ids, links)
|
|
|
|
%{links: length(links), skipped: skipped, by_motif: by_motif, themes: map_size(themes)}
|
|
end
|
|
|
|
defp ensure_motif_theme(theme, attrs) do
|
|
if theme.kind == :motif and (theme.description || "") == attrs.description do
|
|
theme
|
|
else
|
|
{:ok, updated} =
|
|
Themes.update_theme(theme, %{kind: :motif, description: attrs.description})
|
|
|
|
updated
|
|
end
|
|
end
|
|
|
|
defp probe(fen), do: probe_module().probe_local_detail(fen)
|
|
|
|
defp probe_module do
|
|
Application.get_env(:chesstrainer, :motif_probe, FathomBackend)
|
|
end
|
|
|
|
defp maybe_only_move(acc, outcome, moves, preserving) do
|
|
if outcome in [:win, :draw] and length(moves) > 1 and length(preserving) == 1 do
|
|
[:only_move | acc]
|
|
else
|
|
acc
|
|
end
|
|
end
|
|
|
|
defp maybe_underpromotion(acc, preserving) do
|
|
underpromotes? =
|
|
Enum.any?(preserving, fn {_wdl, _from, _to, promotes, _ep, _dtz} ->
|
|
promotes in [2, 3, 4]
|
|
end)
|
|
|
|
queen_promotes? =
|
|
Enum.any?(preserving, fn {_wdl, _from, _to, promotes, _ep, _dtz} ->
|
|
promotes == 1
|
|
end)
|
|
|
|
if underpromotes? and not queen_promotes?, do: [:underpromotion | acc], else: acc
|
|
end
|
|
|
|
defp maybe_fifty_move(acc, wdl, dtz, halfmove_clock) do
|
|
table_draw? = wdl in [:cursed_win, :blessed_loss]
|
|
|
|
clock_exhausted? =
|
|
wdl == :win and is_integer(dtz) and dtz > 100 - halfmove_clock
|
|
|
|
if table_draw? or clock_exhausted?, do: [:fifty_move_draw | acc], else: acc
|
|
end
|
|
|
|
defp halfmove_clock(fen) do
|
|
case String.split(fen, " ") do
|
|
[_board, _active, _castling, _ep, clock, _fullmove] ->
|
|
case Integer.parse(clock) do
|
|
{value, _rest} -> value
|
|
:error -> 0
|
|
end
|
|
|
|
_ ->
|
|
0
|
|
end
|
|
end
|
|
end
|