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
This commit is contained in:
2026-11-17 22:37:37 +01:00
committed by GitHub
parent e6f08e0ca6
commit 2759b34296
6 changed files with 493 additions and 0 deletions
+198
View File
@@ -0,0 +1,198 @@
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
@@ -80,6 +80,38 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.Fathom do
end end
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 defp fallback(fen) do
(Application.get_env(:chesstrainer, :tablebase_fallback) || Lichess).probe(fen) (Application.get_env(:chesstrainer, :tablebase_fallback) || Lichess).probe(fen)
end end
+22
View File
@@ -18,6 +18,28 @@ defmodule Chesstrainer.Release do
{:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :down, to: version)) {:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :down, to: version))
end end
@doc """
Derives material family themes for the whole library.
Runs in the release without starting the web application: `with_repo/2`
starts just the repository, which is all the derivation needs.
"""
def derive_material, do: with_repo(&Chesstrainer.Endgames.MaterialThemes.derive/0)
@doc """
Derives motif themes from the local tablebase for the whole library.
"""
def derive_motifs, do: with_repo(&Chesstrainer.Endgames.MotifThemes.derive/0)
defp with_repo(fun) do
load_app()
for repo <- repos() do
{:ok, result, _} = Ecto.Migrator.with_repo(repo, fn _repo -> fun.() end)
result
end
end
defp repos do defp repos do
Application.fetch_env!(@app, :ecto_repos) Application.fetch_env!(@app, :ecto_repos)
end end
+32
View File
@@ -0,0 +1,32 @@
defmodule Mix.Tasks.Themes.DeriveMotifs do
use Mix.Task
@shortdoc "Tags every endgame with its tablebase-proved motifs"
@moduledoc """
Derives only-move, underpromotion and 50-move-draw motifs from the local
Syzygy tablebase.
mix themes.derive_motifs
The pass never calls the remote tablebase. Positions the local files cannot
answer are skipped and reported. Re-running is idempotent: only links to the
motif themes are replaced, so material, curated and community links survive.
"""
@impl Mix.Task
def run(_args) do
Mix.Task.run("app.start")
%{links: links, skipped: skipped, by_motif: by_motif, themes: themes} =
Chesstrainer.Endgames.MotifThemes.derive()
Mix.shell().info(
"Motif themes: #{themes} themes, #{links} link(s) written, #{skipped} endgame(s) skipped."
)
for {motif, count} <- Enum.sort(by_motif) do
Mix.shell().info(" #{motif}: #{count}")
end
end
end
@@ -0,0 +1,170 @@
defmodule Chesstrainer.Endgames.MotifThemesTest.Stub do
@moduledoc false
def probe_local_detail(fen), do: Map.fetch!(Process.get(:motif_stub), fen)
end
defmodule Chesstrainer.Endgames.MotifThemesTest do
use Chesstrainer.DataCase
import Ecto.Query
alias Chesstrainer.Endgames
alias Chesstrainer.Endgames.MotifThemes
alias Chesstrainer.Repo
alias Chesstrainer.Themes
setup do
previous = Application.get_env(:chesstrainer, :motif_probe)
Application.put_env(:chesstrainer, :motif_probe, __MODULE__.Stub)
on_exit(fn ->
if previous,
do: Application.put_env(:chesstrainer, :motif_probe, previous),
else: Application.delete_env(:chesstrainer, :motif_probe)
end)
:ok
end
describe "motifs_for/4" do
test "detects an only move for wins and draws" do
assert [:only_move] = MotifThemes.motifs_for(:win, 5, [move(:win), move(:draw)], 0)
assert [:only_move] =
MotifThemes.motifs_for(:draw, 5, [move(:draw), move(:loss), move(:loss)], 0)
end
test "does not report an only move when several moves preserve the result" do
assert [] = MotifThemes.motifs_for(:win, 5, [move(:win), move(:win)], 0)
end
test "does not report an only move for a forced single move or a lost position" do
assert [] = MotifThemes.motifs_for(:win, 5, [move(:win)], 0)
assert [] = MotifThemes.motifs_for(:loss, 5, [move(:loss), move(:loss)], 0)
end
test "requires an underpromotion while no queen promotion preserves the result" do
assert [:underpromotion] =
MotifThemes.motifs_for(:win, 5, [move(:win, 4), move(:win), move(:draw, 1)], 0)
assert [] = MotifThemes.motifs_for(:win, 5, [move(:win, 4), move(:win, 1)], 0)
assert [] = MotifThemes.motifs_for(:win, 5, [move(:draw, 4), move(:win), move(:win)], 0)
end
test "detects the 50-move rule from the raw WDL" do
assert [:fifty_move_draw] =
MotifThemes.motifs_for(:cursed_win, 120, [move(:cursed_win)], 0)
assert [:fifty_move_draw] =
MotifThemes.motifs_for(:blessed_loss, 120, [move(:blessed_loss)], 0)
end
test "detects the 50-move rule when the clock runs out before the next zeroing move" do
assert [:fifty_move_draw] = MotifThemes.motifs_for(:win, 60, [move(:win)], 50)
assert [] = MotifThemes.motifs_for(:win, 40, [move(:win)], 50)
assert [] = MotifThemes.motifs_for(:win, 100, [move(:win)], 0)
end
test "a position can carry several motifs" do
assert [:underpromotion, :only_move] =
MotifThemes.motifs_for(:win, 5, [move(:win, 4), move(:draw)], 0)
end
end
describe "derive/0" do
@win_fen "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1"
@draw_fen "4k3/8/8/8/8/4p3/4P3/4K3 w - - 0 1"
@loss_fen "8/8/3k4/8/8/3K4/8/6q1 w - - 0 1"
test "links the motifs reported for each endgame and skips losses" do
win = create_endgame!(@win_fen, :win)
draw = create_endgame!(@draw_fen, :draw)
loss = create_endgame!(@loss_fen, :loss)
stub(%{
win.fen => {:ok, %{wdl: :win, dtz: 5, moves: [move(:win), move(:draw)]}},
draw.fen => {:ok, %{wdl: :cursed_win, dtz: 120, moves: [move(:cursed_win)]}}
})
assert %{links: 2, skipped: 0, themes: 3} = MotifThemes.derive()
assert theme_names(win) == ["only move"]
assert theme_names(draw) == ["50-move draw"]
assert theme_names(loss) == []
assert Enum.all?(Themes.list_themes(), &(&1.kind == :motif))
assert Enum.all?(Themes.list_themes(), &(&1.description not in [nil, ""]))
end
test "reports endgames the local tables cannot answer" do
endgame = create_endgame!(@win_fen, :win)
stub(%{endgame.fen => {:error, :unsupported}})
assert %{links: 0, skipped: 1} = MotifThemes.derive()
assert theme_names(endgame) == []
end
test "is idempotent and leaves material, curated and community links alone" do
win = create_endgame!(@win_fen, :win)
stub(%{win.fen => {:ok, %{wdl: :win, dtz: 5, moves: [move(:win), move(:draw)]}}})
{:ok, lucena} = Themes.create_theme(%{name: "Lucena", category: :endgame})
{:ok, rook_endgame} =
Themes.create_theme(%{name: "rook endgame", kind: :material, category: :endgame})
{:ok, _} = Themes.tag_endgames(lucena, [win.id], :curated)
:ok = Themes.sync_derived_themes(win.id, [rook_endgame.id])
MotifThemes.derive()
first = link_rows(win.id)
MotifThemes.derive()
assert link_rows(win.id) == first
assert {lucena.id, "curated"} in first
assert {rook_endgame.id, "derived"} in first
assert length(first) == 3
end
test "corrects an existing technique theme into a motif theme" do
{:ok, existing} = Themes.create_theme(%{name: "only move", category: :endgame})
endgame = create_endgame!(@win_fen, :win)
stub(%{endgame.fen => {:ok, %{wdl: :win, dtz: 5, moves: [move(:win), move(:draw)]}}})
MotifThemes.derive()
theme = Themes.get_theme!(existing.id)
assert theme.kind == :motif
assert theme.description =~ "Exactly one legal move"
end
end
defp stub(responses), do: Process.put(:motif_stub, responses)
defp move(wdl, promotes \\ 0, dtz \\ 0), do: {wdl, 0, 0, promotes, 0, dtz}
defp create_endgame!(fen, result) do
{:ok, endgame} =
Endgames.create_endgame(%{fen: fen, color: :white, result: result, rating: 1500})
endgame
end
defp theme_names(endgame) do
endgame
|> Map.fetch!(:id)
|> link_rows()
|> Enum.map(fn {theme_id, _source} -> Themes.get_theme!(theme_id).name end)
|> Enum.sort()
end
defp link_rows(endgame_id) do
Repo.all(
from l in "endgames_themes",
where: l.endgame_id == type(^endgame_id, :binary_id),
select: {l.theme_id, l.source},
order_by: l.theme_id
)
end
end
@@ -6,6 +6,11 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest.Stub do
def probe(_fen), do: {:ok, %Tablebase{category: :draw, checkmate: false, moves: []}} def probe(_fen), do: {:ok, %Tablebase{category: :draw, checkmate: false, moves: []}}
end end
defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest.ExplodingFallback do
@moduledoc false
def probe(_fen), do: raise("the remote tablebase must not be called")
end
defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest do defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest do
# Not async: the local backend reads app config and Fathom keeps global state. # Not async: the local backend reads app config and Fathom keeps global state.
use ExUnit.Case, async: false use ExUnit.Case, async: false
@@ -18,6 +23,7 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest do
@krk "4k3/8/8/8/8/8/8/R3K3 w - - 0 1" @krk "4k3/8/8/8/8/8/8/R3K3 w - - 0 1"
@mate "7k/6Q1/5K2/8/8/8/8/8 b - - 0 1" @mate "7k/6Q1/5K2/8/8/8/8/8 b - - 0 1"
@kpk "8/8/3k4/8/8/3KP3/8/8 w - - 0 1"
test "probes a KRvK position locally" do test "probes a KRvK position locally" do
assert {:ok, %Tablebase{} = tablebase} = FathomBackend.probe(@krk) assert {:ok, %Tablebase{} = tablebase} = FathomBackend.probe(@krk)
@@ -82,4 +88,37 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest do
assert {:ok, %Tablebase{category: :draw}} = FathomBackend.probe(@krk) assert {:ok, %Tablebase{category: :draw}} = FathomBackend.probe(@krk)
end end
end end
describe "probe_local_detail/1" do
test "returns the raw root WDL, DTZ and every legal move" do
assert {:ok, %{wdl: :win, dtz: dtz, moves: moves}} =
FathomBackend.probe_local_detail(@krk)
assert is_integer(dtz)
assert length(moves) == 15
assert Enum.all?(moves, &(elem(&1, 0) in [:win, :cursed_win, :draw, :blessed_loss, :loss]))
end
test "returns terminal for a finished position" do
assert {:error, :terminal} = FathomBackend.probe_local_detail(@mate)
end
test "returns unsupported when the local files cannot answer the position" do
assert {:error, :unsupported} = FathomBackend.probe_local_detail(@kpk)
end
test "never calls the remote backend" do
previous = Application.get_env(:chesstrainer, :tablebase_fallback)
on_exit(fn ->
if previous,
do: Application.put_env(:chesstrainer, :tablebase_fallback, previous),
else: Application.delete_env(:chesstrainer, :tablebase_fallback)
end)
Application.put_env(:chesstrainer, :tablebase_fallback, __MODULE__.ExplodingFallback)
assert {:error, :unsupported} = FathomBackend.probe_local_detail(@kpk)
end
end
end end