Files
owenrees 2759b34296 Derive only-move, underpromotion and 50-move motif themes (#195)
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
2026-11-17 22:37:37 +01:00

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