mirror of
https://github.com/TheRealOwenRees/chess-endgame-trainer.git
synced 2026-11-18 03:32:06 +00:00
Derive disjoint material family themes from each endgame's Key (#193)
Every endgame now belongs to exactly one material family derived from its Key: pawn, rook, rook and pawn, queen, queen and pawn, minor piece, minor piece and pawn, basic mate, king and pawn, or bare king other. The bare-king families are split out because those positions teach a mating or promotion technique rather than a general material class. Family membership is objective, so a derivation pass owns links to its themes: refreshing rewrites them as derived and removes a curated link that contradicts the family, while technique themes are untouched. Re-running is idempotent. A mix task applies the mapping to the whole library. Seeds add the king technique themes for later human tagging. Closes #186
This commit is contained in:
@@ -0,0 +1,215 @@
|
||||
defmodule Chesstrainer.Endgames.MaterialThemes do
|
||||
@moduledoc """
|
||||
Derives each endgame's material family from its canonical Key.
|
||||
|
||||
Every endgame belongs to exactly one family, so the themes behave as a
|
||||
partition: selecting several in a filter produces their union, never an
|
||||
ambiguous intersection. A lone king against heavy or pawn material is split
|
||||
out because those positions teach a specific technique — basic mate or
|
||||
promotion — rather than a general material class.
|
||||
|
||||
Families are derived, never judged. They are stored with source `derived`, so
|
||||
a refresh replaces them without touching curated or community themes.
|
||||
Positions with no legal content (`K v K`) and rows without a Key are skipped.
|
||||
"""
|
||||
|
||||
import Ecto.Query, warn: false
|
||||
|
||||
alias Chesstrainer.Endgames.Endgame
|
||||
alias Chesstrainer.Repo
|
||||
alias Chesstrainer.Themes
|
||||
|
||||
@families [
|
||||
basic_mate: %{
|
||||
name: "basic mate",
|
||||
description:
|
||||
"A lone king against the queen or a rook, with no pawns: the puzzle is about delivering mate."
|
||||
},
|
||||
king_and_pawn: %{
|
||||
name: "king and pawn",
|
||||
description:
|
||||
"A lone king against king and pawns: the puzzle is about promotion, or holding the draw."
|
||||
},
|
||||
bare_king_other: %{
|
||||
name: "bare king other",
|
||||
description:
|
||||
"A lone king against minor pieces, or against pawns and pieces: usually a technique exercise with little counterplay."
|
||||
},
|
||||
queen_and_pawn: %{
|
||||
name: "queen and pawn",
|
||||
description: "Queens and pawns on the board."
|
||||
},
|
||||
queen_endgame: %{
|
||||
name: "queen endgame",
|
||||
description: "Queens on the board, with no pawns."
|
||||
},
|
||||
rook_and_pawn: %{
|
||||
name: "rook and pawn",
|
||||
description: "Rooks and pawns, with no queens."
|
||||
},
|
||||
rook_endgame: %{
|
||||
name: "rook endgame",
|
||||
description: "Rooks, with no queens and no pawns."
|
||||
},
|
||||
minor_piece_and_pawn: %{
|
||||
name: "minor piece and pawn",
|
||||
description: "Bishops and knights with pawns, with no queens or rooks."
|
||||
},
|
||||
minor_piece_endgame: %{
|
||||
name: "minor piece endgame",
|
||||
description: "Bishops and knights, with no queens, rooks or pawns."
|
||||
},
|
||||
pawn_endgame: %{
|
||||
name: "pawn endgame",
|
||||
description: "Kings and pawns only."
|
||||
}
|
||||
]
|
||||
|
||||
@type family ::
|
||||
:basic_mate
|
||||
| :king_and_pawn
|
||||
| :bare_king_other
|
||||
| :queen_and_pawn
|
||||
| :queen_endgame
|
||||
| :rook_and_pawn
|
||||
| :rook_endgame
|
||||
| :minor_piece_and_pawn
|
||||
| :minor_piece_endgame
|
||||
| :pawn_endgame
|
||||
|
||||
@doc "The material families, in a stable order."
|
||||
def families, do: @families
|
||||
|
||||
@doc """
|
||||
Returns the material family for a Key.
|
||||
|
||||
Returns `:kings_only` for `"K v K"` and `:unknown` when the Key is missing or
|
||||
not shaped like `"<side> v <side>"`.
|
||||
"""
|
||||
@spec family(String.t() | nil) :: family() | :kings_only | :unknown
|
||||
def family(key) when is_binary(key) do
|
||||
case String.split(key, " v ") do
|
||||
[a, b] ->
|
||||
cond do
|
||||
bare?(a) and bare?(b) -> :kings_only
|
||||
bare?(a) -> bare_king_family(counts(b))
|
||||
bare?(b) -> bare_king_family(counts(a))
|
||||
true -> material_family(merge(counts(a), counts(b)))
|
||||
end
|
||||
|
||||
_ ->
|
||||
:unknown
|
||||
end
|
||||
end
|
||||
|
||||
def family(_key), do: :unknown
|
||||
|
||||
@doc """
|
||||
Creates or corrects the material themes, keyed by family.
|
||||
|
||||
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 material theme
|
||||
without losing its existing links.
|
||||
"""
|
||||
@spec ensure_themes() :: %{family() => Chesstrainer.Themes.Theme.t()}
|
||||
def ensure_themes do
|
||||
Map.new(@families, fn {family, attrs} ->
|
||||
{:ok, theme} = Themes.get_or_create(attrs.name, "endgame", kind: :material)
|
||||
{family, ensure_material_theme(theme, attrs)}
|
||||
end)
|
||||
end
|
||||
|
||||
@doc """
|
||||
Refreshes every endgame's derived material theme.
|
||||
|
||||
Returns the number of endgames tagged, the number skipped (kings only or no
|
||||
Key) and the number of material themes. Re-running is idempotent.
|
||||
"""
|
||||
@spec derive() :: %{
|
||||
tagged: non_neg_integer(),
|
||||
skipped: non_neg_integer(),
|
||||
themes: non_neg_integer()
|
||||
}
|
||||
def derive do
|
||||
themes = ensure_themes()
|
||||
material_ids = Enum.map(themes, fn {_family, theme} -> theme.id end)
|
||||
|
||||
{links, skipped} =
|
||||
Endgame
|
||||
|> select([e], {e.id, e.key})
|
||||
|> Repo.all()
|
||||
|> Enum.reduce({[], 0}, fn {id, key}, {links, skipped} ->
|
||||
case family(key) do
|
||||
family when family in [:kings_only, :unknown] ->
|
||||
{links, skipped + 1}
|
||||
|
||||
family ->
|
||||
{[{id, Map.fetch!(themes, family).id} | links], skipped}
|
||||
end
|
||||
end)
|
||||
|
||||
:ok = Themes.replace_theme_links(material_ids, links)
|
||||
|
||||
%{tagged: length(links), skipped: skipped, themes: map_size(themes)}
|
||||
end
|
||||
|
||||
defp ensure_material_theme(theme, attrs) do
|
||||
if theme.kind == :material and (theme.description || "") == attrs.description do
|
||||
theme
|
||||
else
|
||||
{:ok, updated} =
|
||||
Themes.update_theme(theme, %{kind: :material, description: attrs.description})
|
||||
|
||||
updated
|
||||
end
|
||||
end
|
||||
|
||||
defp bare?(side), do: side == "K"
|
||||
|
||||
defp bare_king_family(counts) do
|
||||
cond do
|
||||
count(counts, "P") == 0 and (count(counts, "Q") > 0 or count(counts, "R") > 0) ->
|
||||
:basic_mate
|
||||
|
||||
count(counts, "P") > 0 and count(counts, "Q") == 0 and count(counts, "R") == 0 ->
|
||||
:king_and_pawn
|
||||
|
||||
true ->
|
||||
:bare_king_other
|
||||
end
|
||||
end
|
||||
|
||||
defp material_family(counts) do
|
||||
cond do
|
||||
count(counts, "Q") > 0 and count(counts, "P") > 0 ->
|
||||
:queen_and_pawn
|
||||
|
||||
count(counts, "Q") > 0 ->
|
||||
:queen_endgame
|
||||
|
||||
count(counts, "R") > 0 and count(counts, "P") > 0 ->
|
||||
:rook_and_pawn
|
||||
|
||||
count(counts, "R") > 0 ->
|
||||
:rook_endgame
|
||||
|
||||
count(counts, "B") + count(counts, "N") > 0 and count(counts, "P") > 0 ->
|
||||
:minor_piece_and_pawn
|
||||
|
||||
count(counts, "B") + count(counts, "N") > 0 ->
|
||||
:minor_piece_endgame
|
||||
|
||||
count(counts, "P") > 0 ->
|
||||
:pawn_endgame
|
||||
|
||||
true ->
|
||||
:kings_only
|
||||
end
|
||||
end
|
||||
|
||||
defp counts(side), do: Enum.frequencies(String.graphemes(side))
|
||||
|
||||
defp merge(left, right), do: Map.merge(left, right, fn _piece, a, b -> a + b end)
|
||||
|
||||
defp count(counts, piece), do: Map.get(counts, piece, 0)
|
||||
end
|
||||
@@ -221,6 +221,48 @@ defmodule Chesstrainer.Themes do
|
||||
end
|
||||
end
|
||||
|
||||
@doc """
|
||||
Replaces every link to `scoped_theme_ids` with the derived links in `links`.
|
||||
|
||||
This is for themes that are objectively derived: the pass owns its themes
|
||||
entirely, so a link's previous source is irrelevant and every link is
|
||||
rewritten as `derived`. Links to themes outside `scoped_theme_ids` — curated
|
||||
or community — are untouched.
|
||||
|
||||
The operation is a full refresh for the given themes, so it can move an
|
||||
endgame between families when a rule changes. `links` is a list of
|
||||
`{endgame_id, theme_id}` pairs.
|
||||
"""
|
||||
@spec replace_theme_links([term()], [{Ecto.UUID.t(), term()}]) :: :ok
|
||||
def replace_theme_links(scoped_theme_ids, links) when is_list(links) do
|
||||
now = DateTime.utc_now() |> DateTime.truncate(:second)
|
||||
|
||||
Repo.transaction(fn ->
|
||||
if scoped_theme_ids != [] do
|
||||
Repo.delete_all(
|
||||
from l in "endgames_themes",
|
||||
where: l.theme_id in ^scoped_theme_ids
|
||||
)
|
||||
end
|
||||
|
||||
links
|
||||
|> Enum.map(fn {endgame_id, theme_id} ->
|
||||
%{
|
||||
endgame_id: Ecto.UUID.dump!(endgame_id),
|
||||
theme_id: theme_id,
|
||||
source: "derived",
|
||||
inserted_at: now
|
||||
}
|
||||
end)
|
||||
|> Enum.chunk_every(5_000)
|
||||
|> Enum.each(fn rows ->
|
||||
Repo.insert_all("endgames_themes", rows, on_conflict: :nothing)
|
||||
end)
|
||||
end)
|
||||
|
||||
:ok
|
||||
end
|
||||
|
||||
@doc """
|
||||
Replaces the derived theme links for one endgame.
|
||||
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
defmodule Mix.Tasks.Themes.DeriveMaterial do
|
||||
use Mix.Task
|
||||
|
||||
@shortdoc "Tags every endgame with its material family theme"
|
||||
|
||||
@moduledoc """
|
||||
Derives each endgame's material family from its Key and stores the result as
|
||||
a derived theme.
|
||||
|
||||
mix themes.derive_material
|
||||
|
||||
Every endgame belongs to exactly one family, so the themes partition the
|
||||
library. Re-running is idempotent: only derived links are replaced, and
|
||||
curated or community links are untouched.
|
||||
|
||||
Positions that are kings only, or that have no Key, are reported as skipped.
|
||||
"""
|
||||
|
||||
@impl Mix.Task
|
||||
def run(_args) do
|
||||
Mix.Task.run("app.start")
|
||||
|
||||
%{tagged: tagged, skipped: skipped, themes: themes} =
|
||||
Chesstrainer.Endgames.MaterialThemes.derive()
|
||||
|
||||
Mix.shell().info(
|
||||
"Material themes: #{themes} themes, #{tagged} endgames tagged, " <>
|
||||
"#{skipped} skipped (kings only or no Key)."
|
||||
)
|
||||
end
|
||||
end
|
||||
@@ -6,8 +6,7 @@ defmodule Chesstrainer.Repo.Seeds.Endgames.Win do
|
||||
color: :white,
|
||||
message: "Rook vs king endgame",
|
||||
notes: "Basic rook endgame",
|
||||
result: :win,
|
||||
themes: ["rook endgame"]
|
||||
result: :win
|
||||
},
|
||||
%{
|
||||
fen: "8/8/8/1P4p1/5k2/5p2/P6K/8 b - - 0 0",
|
||||
|
||||
@@ -8,6 +8,10 @@ defmodule Chesstrainer.Repo.Seeds.Themes do
|
||||
"Lucena",
|
||||
"Philidor",
|
||||
"opposition",
|
||||
"key squares",
|
||||
"triangulation",
|
||||
"shouldering",
|
||||
"king activity",
|
||||
"promotion",
|
||||
"stalemate"
|
||||
]
|
||||
|
||||
@@ -0,0 +1,173 @@
|
||||
defmodule Chesstrainer.Endgames.MaterialThemesTest do
|
||||
use Chesstrainer.DataCase
|
||||
|
||||
import Ecto.Query
|
||||
|
||||
alias Chesstrainer.Endgames
|
||||
alias Chesstrainer.Endgames.MaterialThemes
|
||||
alias Chesstrainer.Repo
|
||||
alias Chesstrainer.Themes
|
||||
|
||||
@kr_v_k "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1"
|
||||
@kp_v_k "8/8/3k4/8/8/3KP3/8/8 w - - 0 1"
|
||||
@kbn_v_k "8/8/3k4/8/8/3KBN2/8/8 w - - 0 1"
|
||||
@krp_v_k "8/8/3k4/8/8/3KR2P/8/8 w - - 0 1"
|
||||
@kp_v_kp "4k3/8/8/8/8/4p3/4P3/4K3 w - - 0 1"
|
||||
@kq_v_kp "8/8/3k4/8/8/3K1Q1p/8/8 w - - 0 1"
|
||||
@kq_v_kq "3q4/8/3k4/8/8/3K1Q2/8/8 w - - 0 1"
|
||||
@kn_v_kp "8/8/3k4/8/8/3KN2p/8/8 w - - 0 1"
|
||||
@kb_v_kb "8/8/3k1b2/8/8/3K1B2/8/8 w - - 0 1"
|
||||
@krp_v_kr "8/8/3k4/8/8/3KR2P/8/5r2 w - - 0 1"
|
||||
@kr_v_kr "8/8/3k4/8/8/3K1R2/8/5r2 b - - 0 1"
|
||||
@k_v_k "8/8/3k4/8/8/3K4/8/8 w - - 0 1"
|
||||
|
||||
describe "family/1" do
|
||||
test "classifies a lone king against heavy or pawn material" do
|
||||
assert MaterialThemes.family("KQ v K") == :basic_mate
|
||||
assert MaterialThemes.family("KR v K") == :basic_mate
|
||||
assert MaterialThemes.family("KP v K") == :king_and_pawn
|
||||
assert MaterialThemes.family("KPP v K") == :king_and_pawn
|
||||
assert MaterialThemes.family("KBN v K") == :bare_king_other
|
||||
assert MaterialThemes.family("KRP v K") == :bare_king_other
|
||||
end
|
||||
|
||||
test "classifies material presence into one family" do
|
||||
assert MaterialThemes.family("KP v KP") == :pawn_endgame
|
||||
assert MaterialThemes.family("KQ v KP") == :queen_and_pawn
|
||||
assert MaterialThemes.family("KQ v KQ") == :queen_endgame
|
||||
assert MaterialThemes.family("KRP v KR") == :rook_and_pawn
|
||||
assert MaterialThemes.family("KR v KR") == :rook_endgame
|
||||
assert MaterialThemes.family("KN v KP") == :minor_piece_and_pawn
|
||||
assert MaterialThemes.family("KB v KB") == :minor_piece_endgame
|
||||
end
|
||||
|
||||
test "flags content-free and malformed keys" do
|
||||
assert MaterialThemes.family("K v K") == :kings_only
|
||||
assert MaterialThemes.family(nil) == :unknown
|
||||
assert MaterialThemes.family("not a key") == :unknown
|
||||
end
|
||||
end
|
||||
|
||||
describe "derive/0" do
|
||||
test "creates every material family as a material theme" do
|
||||
MaterialThemes.derive()
|
||||
|
||||
themes = Themes.list_themes()
|
||||
|
||||
assert length(themes) == length(MaterialThemes.families())
|
||||
assert Enum.all?(themes, &(&1.kind == :material))
|
||||
assert Enum.all?(themes, &(&1.description not in [nil, ""]))
|
||||
end
|
||||
|
||||
test "tags every endgame with exactly one family" do
|
||||
pawn = create_endgame!(@kp_v_kp)
|
||||
rook = create_endgame!(@kr_v_kr)
|
||||
rook_and_pawn = create_endgame!(@krp_v_kr)
|
||||
queen_and_pawn = create_endgame!(@kq_v_kp)
|
||||
queen = create_endgame!(@kq_v_kq)
|
||||
minor_and_pawn = create_endgame!(@kn_v_kp)
|
||||
minor = create_endgame!(@kb_v_kb)
|
||||
mate = create_endgame!(@kr_v_k)
|
||||
promotion = create_endgame!(@kp_v_k)
|
||||
bare_minor = create_endgame!(@kbn_v_k)
|
||||
bare_other = create_endgame!(@krp_v_k)
|
||||
kings_only = create_endgame!(@k_v_k)
|
||||
|
||||
assert %{tagged: 11, skipped: 1} = MaterialThemes.derive()
|
||||
|
||||
assert ["pawn endgame"] = theme_names(pawn)
|
||||
assert ["rook endgame"] = theme_names(rook)
|
||||
assert ["rook and pawn"] = theme_names(rook_and_pawn)
|
||||
assert ["queen and pawn"] = theme_names(queen_and_pawn)
|
||||
assert ["queen endgame"] = theme_names(queen)
|
||||
assert ["minor piece and pawn"] = theme_names(minor_and_pawn)
|
||||
assert ["minor piece endgame"] = theme_names(minor)
|
||||
assert ["basic mate"] = theme_names(mate)
|
||||
assert ["king and pawn"] = theme_names(promotion)
|
||||
assert ["bare king other"] = theme_names(bare_minor)
|
||||
assert ["bare king other"] = theme_names(bare_other)
|
||||
assert [] = theme_names(kings_only)
|
||||
end
|
||||
|
||||
test "corrects an existing technique theme and claims its links as derived" do
|
||||
{:ok, existing} = Themes.create_theme(%{name: "rook endgame", category: :endgame})
|
||||
endgame = create_endgame!(@kr_v_kr, [existing])
|
||||
|
||||
MaterialThemes.derive()
|
||||
|
||||
theme = Themes.get_theme!(existing.id)
|
||||
assert theme.kind == :material
|
||||
assert theme.description =~ "Rooks"
|
||||
|
||||
assert [{theme_id, "derived"}] = link_rows(endgame.id)
|
||||
assert theme_id == existing.id
|
||||
end
|
||||
|
||||
test "removes a curated link to a material theme that contradicts the family" do
|
||||
{:ok, rook} = Themes.create_theme(%{name: "rook endgame", category: :endgame})
|
||||
mate = create_endgame!(@kr_v_k, [rook])
|
||||
|
||||
MaterialThemes.derive()
|
||||
|
||||
assert ["basic mate"] = theme_names(mate)
|
||||
end
|
||||
|
||||
test "is idempotent" do
|
||||
endgame = create_endgame!(@kq_v_kp)
|
||||
|
||||
MaterialThemes.derive()
|
||||
first = link_rows(endgame.id)
|
||||
MaterialThemes.derive()
|
||||
|
||||
assert link_rows(endgame.id) == first
|
||||
assert length(first) == 1
|
||||
end
|
||||
|
||||
test "leaves curated and community links to other themes alone" do
|
||||
{:ok, lucena} = Themes.create_theme(%{name: "Lucena", category: :endgame})
|
||||
endgame = create_endgame!(@kr_v_kr)
|
||||
insert_link(endgame.id, lucena.id, "community")
|
||||
|
||||
MaterialThemes.derive()
|
||||
|
||||
rows = link_rows(endgame.id)
|
||||
assert {lucena.id, "community"} in rows
|
||||
assert length(rows) == 2
|
||||
end
|
||||
end
|
||||
|
||||
defp create_endgame!(fen, themes \\ []) do
|
||||
{:ok, endgame} =
|
||||
Endgames.create_endgame(%{fen: fen, color: :white, result: :win, rating: 1500}, themes)
|
||||
|
||||
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
|
||||
|
||||
defp insert_link(endgame_id, theme_id, source) do
|
||||
Repo.insert_all("endgames_themes", [
|
||||
%{
|
||||
endgame_id: Ecto.UUID.dump!(endgame_id),
|
||||
theme_id: theme_id,
|
||||
source: source,
|
||||
inserted_at: DateTime.utc_now() |> DateTime.truncate(:second)
|
||||
}
|
||||
])
|
||||
end
|
||||
end
|
||||
Reference in New Issue
Block a user