helpmate-tablebase

Every helpmate in a material class, solved: for every legal position, how many moves the mate takes and how many different solutions reach it. Complete through six pieces: all 1,001 material classes from two to six men. MIT licensed; the tables are a free download.

h#5   (2+4)

Black moves first and helps White mate in five. White has a king and a single bishop. Black has a queen, a bishop and a knight, and all three end up working for White. There is exactly one way to do it.

1.Bb5 Ba2 2.Kc2 Bb1+ 3.Kb3 Ba2+ 4.Ka4 Kb2 5.Qa5 Bb3#

The black king walks into a corner its own army has walled off. Queen, bishop and knight block a5, b5 and b4, the white king covers a3 and guards b3, and the bishop mates from b3 after swinging a2, b1, a2 to steer the king. Every piece on the board takes part: an ideal mate.

Nobody composed this. The table holds 900,409,280 h#5 positions with this material; 4,509,985 of them, about one in two hundred, have a unique solution, and the table knows which.

What the table stores

In a helpmate both sides cooperate: Black moves first and helps White mate in the fewest moves. Composers publish these as h#n problems, and a problem is only sound if its solution is unique.

For every legal position in a material class, the table stores:

• dtm, the distance to mate in plies under optimal cooperation, which is where the composer's h#n comes from;
• count, how many distinct optimal solutions tie for shortest. count=1 is a sound problem, count=2 has a dual.

The count is the point. Anyone can search one position for a mate; the tablebase says whether the mate is unique, for every position at once.

Because both sides want the same thing, solving is a cooperative shortest-path problem rather than the min/max game tree an ordinary tablebase faces. That is what makes whole material classes tractable.

$ helpmate mine KQvk --dtm 2 --count 1 --max 3
8/8/8/8/8/8/8/k1KQ4 b - - 0 1
8/8/8/8/8/2Q5/8/k1K5 b - - 0 1
8/8/8/8/4Q3/8/8/k1K5 b - - 0 1

Three h#1 positions with exactly one solution each: sound problems, enumerated rather than found.

Sixty seconds

$ helpmate gen KQvk --tables tables
tables/Kvk.hm max_dtm=255
tables/KQvk.hm max_dtm=14

$ helpmate probe "8/7k/5K2/8/8/8/8/6Q1 b - - 0 1"
dtm=2 (h#1) count=4

$ helpmate line "8/7k/5K2/8/8/8/8/6Q1 b - - 0 1" --all
Kh6 Qh2#
Kh6 Qh1#
Kh6 Qg6#
Kh8 Qg7#

Black king h7, White king f6, White queen g1. Mate in one move, four different ways, so as a problem it is unsound. The table answered without searching: generation is a one-off cost, and every query afterwards is a lookup.

What is solved today

pieces	classes	status
2–4	66	complete
5	220	complete
6	715	complete (75 of them proven empty)
7	2,002	not started: 1.8 TiB of RAM per pawnless class, more with pawns

1001 tables, 3940.5 GiB block-compressed, published as a Hugging Face dataset. The deepest mate in the corpus is h#17.5.

helpmate-tables pull --tables ./tables --repo osick/helpmate-tables

The server can also stream tables on demand, fetching and caching each class the first time someone asks for it.

Contributors

Most of the six-piece tables were not computed here. They were generated on other people's machines, sent as pull requests to the dataset, verified, and merged with credit. Some were computed twice, independently, and their data matched exactly; that is the reproduced column.

contributor	tables	reproduced	dataset PRs	notes
T31M	584 tablesKBBBBvk, KBBBNvk, KBBBPvk, KBBBvkb, KBBBvkn, KBBBvkp, KBBBvkq, KBBBvkr, KBBNNvk, KBBNPvk, KBBNvkb, KBBNvkn, KBBNvkp, KBBNvkq, KBBNvkr, KBBPPvk, KBBPvkb, KBBPvkn, KBBPvkp, KBBPvkq, KBBPvkr, KBBvkbp, KBBvknp, KBBvkpp, KBBvkqb, KBBvkqn, KBBvkqp, KBBvkqq, KBBvkqr, KBBvkrb, KBBvkrn, KBBvkrp, KBBvkrr, KBNNNvk, KBNNPvk, KBNNvkb, KBNNvkn, KBNNvkp, KBNNvkq, KBNNvkr, KBNPPvk, KBNPvkb, KBNPvkn, KBNPvkp, KBNPvkq, KBNPvkr, KBNvkbb, KBNvkbn, KBNvkbp, KBNvknn, KBNvknp, KBNvkpp, KBNvkqb, KBNvkqn, KBNvkqp, KBNvkqq, KBNvkqr, KBNvkrb, KBNvkrn, KBNvkrp, KBNvkrr, KBPPPvk, KBPPvkb, KBPPvkn, KBPPvkp, KBPPvkq, KBPPvkr, KBPvkbb, KBPvkbn, KBPvkbp, KBPvknn, KBPvknp, KBPvkpp, KBPvkqb, KBPvkqn, KBPvkqp, KBPvkqq, KBPvkqr, KBPvkrb, KBPvkrn, KBPvkrp, KBPvkrr, KBvkbbb, KBvkbbn, KBvkbbp, KBvkbnn, KBvkbnp, KBvkbpp, KBvknnn, KBvknnp, KBvknpp, KBvkppp, KBvkqbp, KBvkqnp, KBvkqpp, KBvkqqp, KBvkqrp, KBvkrbn, KBvkrbp, KBvkrnn, KBvkrnp, KBvkrpp, KBvkrrb, KBvkrrn, KBvkrrp, KNNNNvk, KNNNPvk, KNNPPvk, KNNPvkb, KNNPvkn, KNNPvkp, KNNPvkq, KNNPvkr, KNPPPvk, KNPPvkb, KNPPvkn, KNPPvkp, KNPPvkq, KNPPvkr, KNPvkbb, KNPvkbn, KNPvkbp, KNPvknn, KNPvknp, KNPvkpp, KNPvkqb, KNPvkqn, KNPvkqp, KNPvkqq, KNPvkqr, KNPvkrb, KNPvkrn, KNPvkrp, KNPvkrr, KNvkbbb, KNvkbbn, KNvkbbp, KNvkbnn, KNvkbnp, KNvkbpp, KNvknnp, KNvknpp, KNvkppp, KNvkqbb, KNvkqbn, KNvkqbp, KNvkqnn, KNvkqnp, KNvkqpp, KNvkqqb, KNvkqqn, KNvkqqp, KNvkqqr, KNvkqrb, KNvkqrn, KNvkqrp, KNvkqrr, KNvkrbb, KNvkrbn, KNvkrbp, KNvkrnn, KNvkrnp, KNvkrpp, KNvkrrb, KNvkrrn, KNvkrrp, KNvkrrr, KPPPPvk, KPPPvkb, KPPPvkn, KPPPvkp, KPPPvkq, KPPPvkr, KPPvkbb, KPPvkbn, KPPvkbp, KPPvknn, KPPvknp, KPPvkpp, KPPvkqb, KPPvkqn, KPPvkqp, KPPvkqq, KPPvkqr, KPPvkrb, KPPvkrn, KPPvkrp, KPPvkrr, KPvkbbb, KPvkbbn, KPvkbbp, KPvkbnn, KPvkbnp, KPvkbpp, KPvknnn, KPvknnp, KPvknpp, KPvkppp, KPvkqbb, KPvkqbn, KPvkqbp, KPvkqnn, KPvkqnp, KPvkqpp, KPvkqqb, KPvkqqn, KPvkqqp, KPvkqqq, KPvkqqr, KPvkqrb, KPvkqrn, KPvkqrp, KPvkqrr, KPvkrbb, KPvkrbn, KPvkrbp, KPvkrnn, KPvkrnp, KPvkrpp, KPvkrrb, KPvkrrn, KPvkrrp, KPvkrrr, KQBBBvk, KQBBNvk, KQBBPvk, KQBBvkb, KQBBvkn, KQBBvkp, KQBBvkq, KQBBvkr, KQBNNvk, KQBNPvk, KQBNvkb, KQBNvkn, KQBNvkp, KQBNvkq, KQBNvkr, KQBPPvk, KQBPvkb, KQBPvkn, KQBPvkp, KQBPvkq, KQBPvkr, KQBvkbb, KQBvkbn, KQBvkbp, KQBvknn, KQBvknp, KQBvkpp, KQBvkqb, KQBvkqn, KQBvkqp, KQBvkqq, KQBvkqr, KQBvkrb, KQBvkrn, KQBvkrp, KQBvkrr, KQNNNvk, KQNNPvk, KQNNvkb, KQNNvkn, KQNNvkp, KQNNvkq, KQNNvkr, KQNPPvk, KQNPvkb, KQNPvkn, KQNPvkp, KQNPvkq, KQNPvkr, KQNvkbb, KQNvkbn, KQNvkbp, KQNvknn, KQNvknp, KQNvkpp, KQNvkqb, KQNvkqn, KQNvkqp, KQNvkqq, KQNvkqr, KQNvkrb, KQNvkrn, KQNvkrp, KQNvkrr, KQPPPvk, KQPPvkb, KQPPvkn, KQPPvkp, KQPPvkq, KQPPvkr, KQPvkbb, KQPvkbn, KQPvkbp, KQPvknn, KQPvknp, KQPvkpp, KQPvkqb, KQPvkqn, KQPvkqp, KQPvkqq, KQPvkqr, KQPvkrb, KQPvkrn, KQPvkrp, KQPvkrr, KQQBBvk, KQQBNvk, KQQBPvk, KQQBvkb, KQQBvkn, KQQBvkp, KQQBvkq, KQQBvkr, KQQNNvk, KQQNPvk, KQQNvkb, KQQNvkn, KQQNvkp, KQQNvkq, KQQNvkr, KQQPPvk, KQQPvkb, KQQPvkn, KQQPvkp, KQQPvkq, KQQPvkr, KQQQBvk, KQQQNvk, KQQQPvk, KQQQQvk, KQQQRvk, KQQQvkb, KQQQvkn, KQQQvkp, KQQQvkq, KQQQvkr, KQQRBvk, KQQRNvk, KQQRPvk, KQQRRvk, KQQRvkb, KQQRvkn, KQQRvkp, KQQRvkq, KQQRvkr, KQQvkbb, KQQvkbn, KQQvkbp, KQQvknn, KQQvknp, KQQvkpp, KQQvkqb, KQQvkqn, KQQvkqp, KQQvkqq, KQQvkqr, KQQvkrb, KQQvkrn, KQQvkrp, KQQvkrr, KQRBBvk, KQRBNvk, KQRBPvk, KQRBvkb, KQRBvkn, KQRBvkp, KQRBvkq, KQRBvkr, KQRNNvk, KQRNPvk, KQRNvkb, KQRNvkn, KQRNvkp, KQRNvkq, KQRNvkr, KQRPPvk, KQRPvkb, KQRPvkn, KQRPvkp, KQRPvkq, KQRPvkr, KQRRBvk, KQRRNvk, KQRRPvk, KQRRRvk, KQRRvkb, KQRRvkn, KQRRvkp, KQRRvkq, KQRRvkr, KQRvkbb, KQRvkbn, KQRvkbp, KQRvknn, KQRvknp, KQRvkpp, KQRvkqb, KQRvkqn, KQRvkqp, KQRvkqq, KQRvkqr, KQRvkrb, KQRvkrn, KQRvkrp, KQRvkrr, KQvkbbp, KQvkbnp, KQvkbpp, KQvknnp, KQvknpp, KQvkppp, KQvkqbb, KQvkqbn, KQvkqbp, KQvkqnn, KQvkqnp, KQvkqpp, KQvkqqb, KQvkqqn, KQvkqqp, KQvkqqq, KQvkqqr, KQvkqrb, KQvkqrn, KQvkqrp, KQvkqrr, KQvkrbp, KQvkrnp, KQvkrpp, KQvkrrp, KRBBBvk, KRBBNvk, KRBBPvk, KRBBvkb, KRBBvkn, KRBBvkp, KRBBvkq, KRBBvkr, KRBNNvk, KRBNPvk, KRBNvkb, KRBNvkn, KRBNvkp, KRBNvkq, KRBNvkr, KRBPPvk, KRBPvkb, KRBPvkn, KRBPvkp, KRBPvkq, KRBPvkr, KRBvkbb, KRBvkbn, KRBvkbp, KRBvknn, KRBvknp, KRBvkpp, KRBvkqb, KRBvkqn, KRBvkqp, KRBvkqq, KRBvkqr, KRBvkrb, KRBvkrn, KRBvkrp, KRBvkrr, KRNNNvk, KRNNPvk, KRNNvkb, KRNNvkn, KRNNvkp, KRNNvkq, KRNNvkr, KRNPPvk, KRNPvkb, KRNPvkn, KRNPvkp, KRNPvkq, KRNPvkr, KRNvkbb, KRNvkbn, KRNvkbp, KRNvknn, KRNvknp, KRNvkpp, KRNvkqb, KRNvkqn, KRNvkqp, KRNvkqq, KRNvkqr, KRNvkrb, KRNvkrn, KRNvkrp, KRNvkrr, KRPPPvk, KRPPvkb, KRPPvkn, KRPPvkp, KRPPvkq, KRPPvkr, KRPvkbb, KRPvkbn, KRPvkbp, KRPvknn, KRPvknp, KRPvkpp, KRPvkqb, KRPvkqn, KRPvkqp, KRPvkqq, KRPvkqr, KRPvkrb, KRPvkrn, KRPvkrp, KRPvkrr, KRRBBvk, KRRBNvk, KRRBPvk, KRRBvkb, KRRBvkn, KRRBvkp, KRRBvkq, KRRBvkr, KRRNNvk, KRRNPvk, KRRNvkb, KRRNvkn, KRRNvkp, KRRNvkq, KRRNvkr, KRRPPvk, KRRPvkb, KRRPvkn, KRRPvkp, KRRPvkq, KRRPvkr, KRRRBvk, KRRRNvk, KRRRPvk, KRRRRvk, KRRRvkb, KRRRvkn, KRRRvkp, KRRRvkq, KRRRvkr, KRRvkpp, KRvkbbb, KRvkbbn, KRvkbbp, KRvkbnn, KRvkbnp, KRvkbpp, KRvknnn, KRvknnp, KRvknpp, KRvkppp, KRvkqbb, KRvkqbn, KRvkqbp, KRvkqnn, KRvkqnp, KRvkqpp, KRvkqqb, KRvkqqn, KRvkqqp, KRvkqqq, KRvkqqr, KRvkqrb, KRvkqrn, KRvkqrp, KRvkqrr, KRvkrbb, KRvkrbn, KRvkrbp, KRvkrnn, KRvkrnp, KRvkrpp, KRvkrrb, KRvkrrn, KRvkrrp, KRvkrrr

Every other table was generated by the maintainer.

[!NOTE] Six pieces are complete. Every one of the 715 six-piece classes is solved and published, most of them computed on contributors' machines (the table above). Contributions are still welcome: an independent reproduction of a published table turns a trusted table into a verified one, and seven pieces are the next frontier. How to contribute a tablebase

Problems to look at

• The longest unique problem in every material class, with a diagram and the solution, also as a printable A5 booklet, Longest Helpmates with up to Six Men, in English, German and French. Each problem links to the Helpmate Analyzer with the stipulation already set, and in the booklet carries a QR code for the printed page.
• The showcase site plays them through on a board and has 1071 unique-solution puzzles to solve, filtered by theme. Every material has a page of its own (KQvk, for example) with its deepest unique and deepest dual problems, and a theme index links every theme to every problem that shows it. Static, no server, built from the same data.

These positions were enumerated, not composed. No authorship is claimed over any of them, none will be entered in a composing tourney, and a generated database anticipates nobody: a composer who arrives independently at one of these positions is unaffected. Where a position is already a published composition it is credited to its author. Authorship, anticipation, and what this corpus is for

The command line is the front door

helpmate is the primary interface, and USAGE.md documents all of it:

gen	build every table a material class needs
probe	look up one position
line	print optimal solutions as SAN
mine	scan a class for compositions by dtm, solution count, shape and theme; annotate, export as JSON, or refine interactively
stats	generation statistics and corpus summaries
themes	list the pattern detectors mine --theme accepts
compact	compress tables, or shrink provably-unsolvable ones to markers

mine --theme recognises 33 named composition patterns — pure, model and ideal mates, promotions and excelsior, switchbacks, Umnov, Indian, Zilahi and more. helpmate themes prints the exact definition each detector uses (also in USAGE); the theme catalogue classifies all 295 themes of the Helpmate Analyzer glossary by what a detector would need.

A countable theme also takes a count of occurrences over all optimal solutions: --theme promotion:4 finds four promotions altogether, and --count 2 --theme ideal:2 two solutions that both end in an ideal mate (Counting themes). --dualfree drops positions in which two solutions end in the same mate by different move orders: in KBBvk h#4.5, 29 positions have two model-mate solutions, and one of them has two different model mates (Dual-free).

Mining, from a scan to a shortlist

mine is where compositions come from, and since 0.18.0 a scan is something you can hold on to rather than a stream of FENs you have to probe one by one.

Annotate every hit. --themes adds the themes each position shows, --solutions adds every optimal solution. Text stays greppable: the FEN is the only unindented line.

$ helpmate mine KRvkb --dtm 6 --max 1 --themes --solutions --tables ~/tb
8/8/8/8/8/8/8/K1k1bR2 b - - 0 1
  themes: pure model ideal mirror switchback single-piece single-piece:black nocheck
  Kd1 Ka2 Kc1 Kb3 Kb1 Rxe1#
  Kc2 Ka2 Kc1 Kb3 Kb1 Rxe1#
  Kd2 Ka2 Kc1 Kb3 Kb1 Rxe1#

Take everything. --max infinity (or inf) lifts the cap, and --json turns the result into one document with the material, the filter that was asked, and a positions array carrying fen, dtm, count and, with the flags above, themes (with theme_counts), starts, ends and solutions. For a result too big to parse in one piece, --jsonl writes the same records one per line, streamed as the scan finds them, between a header line and a footer line with the counts:

$ helpmate mine KRvkb --dtm 6 --max infinity --json --themes --solutions --tables ~/tb > krvkb-h3.json
$ helpmate mine KRvkb --dtm 6 --max infinity --jsonl --themes --tables ~/tb | jq -c 'select(.fen and (.themes|index("ideal")))'

Use every core. --threads N scans and annotates on N workers, and the output is identical for every N; --cache-mb N gives the whole scan one memory budget for decompressed blocks. A scan that took 533 s in 0.20 takes 84 s on one thread and 8 s on 14:

$ helpmate mine KBvkqrn --dtm 14 --count 2 --starts 2 --ends 2 --max 100 --threads 14 --tables ~/tb

Refine instead of rescanning. --interactive runs the scan once, keeps the hits in memory, and opens a prompt. Narrowing by theme, solution count or shape works on the held set; each position's themes and solutions are computed the first time they are needed and cached, so back is free and a second filter on the same set costs nothing.

Command	Effect
theme NAME, not theme NAME	keep or drop positions showing NAME (promotions:qrr and counts such as ideal:2 work too)
count N, starts N, ends N	keep positions with exactly that value
dualfree, not dualfree	keep positions with no two solutions ending in the same mate, or the others
back, reset	undo the last narrowing, or return to the loaded set
list [FROM [N]], show I	page through the FENs; print one hit with its themes and every solution
themes	how many positions in the current set show each theme, the map for what to narrow on next
save FILE	.json writes the document above, .jsonl the JSON Lines form; anything else writes bare FENs
help, quit

Results go to stdout and the prompt, progress and notes to stderr, so a scripted session (helpmate mine ... --interactive < script > out) leaves a clean file. There is no line editing built in; rlwrap helpmate ... adds history. The whole thing is in USAGE.md, with the JSON keys and the exact text layout.

Also available

• Python. from helpmate import Tablebase — probe, enumerate lines, and mine from a script. See USAGE.md.
• HTTP API and web dashboard. helpmate-server serves a read-only JSON API and a browser board for exploring positions. Secondary to the CLI, and documented in USAGE.md.

Documentation

USAGE.md	the full guide — every command, every flag, every field
DEEPEST.md	the deepest sound problem in every material class, with diagrams
DEEPEST.pdf	the same showcase as a printable A5 booklet: one page per class with statistics, diagram, solution, themes, published sources and an Analyzer link
DEEPEST_de.pdf, DEEPEST_fr.pdf	the booklet in German and French
DEEPEST.tex	the booklet's LaTeX source (also _de, _fr) — make booklet rebuilds all three PDFs with LuaLaTeX
BUILD.md	prerequisites, build targets, offline dependencies, troubleshooting
CONTRIBUTING-TABLES.md	contribute CPU time and tables
CONTRIBUTING.md	contribute code — CI checks and PR requirements
INTERNALS.md	indexing, generation, storage format, verification, limits

Why you can trust it

A tablebase is worth exactly as much as your reason to believe it. This one does not grade its own homework:

• An independent oracle — a from-scratch cooperative search sharing only the move generator with the real generator — re-solves sampled positions from every slice and checks both dtm and solution count.
• Every one of the 368,452 legal KQvk positions is cross-checked against a reference implementation written directly on python-chess, with no helpmate code involved in computing the expected answers.
• Multithreaded output is required to be byte-identical to single-threaded output, and that is asserted, not assumed.

INTERNALS.md has the full account, including measured coverage and one unresolved bug stated plainly rather than buried.

Building

git clone https://github.com/osick/helpmate-tablebase
cd helpmate-tablebase
make install

Needs a C++20 compiler and CMake. No PyPI release yet. BUILD.md covers the rest.

Licence

MIT. See LICENSE.