Method · AtomicDB docs

PRACTICAL

What "solved" means here

AtomicDB is a persistent, growing tree of Atomic Chess positions. The engine (Atomic-Stockfish) analyses them one at a time, and a position counts as closed (solved) only when one of four checks below proves its result. An engine score on its own never closes anything.

Terms such as node, ply and backed value are in the glossary.

The four ways a position closes

Gate	The position closes when
TERMINAL	It is already over: checkmate, stalemate or an exploded king.
MATE_PV	The engine finds a mate, and the whole mating line is replayed and checked move by move.
MINIMAX	Every legal move has a proven result, so the best of them is the position's result.
SOLVE	A prover on a volunteer machine sends a complete winning strategy, and the server checks all of it.

Exact rules for each gate

TERMINAL: checkmate, stalemate or a king explosion, verified by our own move generator, never by the engine.
MATE_PV: the engine announces a mate and its full line is re-verified move by move down to the terminal position. A mate score alone never closes anything. An exhaustive AND/OR pass labels short mates ANDOR; if its bounded certification budget runs out, the legal engine line (the witness) is labelled ENGINE.
MINIMAX: a three-valued backup over the complete list of legal moves. The list is generated by us; the engine never decides which moves are legal.
SOLVE: a df-pn prover running on a volunteer machine returns a proof certificate. Before anything closes, this server replays the entire strategy tree with its own move generator, a different implementation from the one that produced it. It checks that every cited move is legal, every defender node covers exactly the legal replies, every leaf is genuinely terminal, and no branch repeats a position. A certificate that fails is recorded and changes nothing.

How much to trust a result

ANDOR: the relevant continuations were proved exhaustively, or ended in a verified terminal or tablebase result.
ENGINE: the result still depends on at least one engine line (a witness).
The label is inherited through MINIMAX: a position closed from its moves carries the label those moves earned.
Mate distances such as ≤M4 are honest upper bounds (mate in 4 or sooner), not exact distances.

Why "practical"

Engine evaluations (the centipawn numbers) never close a position. They only decide what to explore next.
Results are "practically solved", the standard used by the Fairy-Stockfish Solved-games wiki. They are not game-theoretic proofs.
The known, declared limitation: a position is identified without its repetition history (see Repetition).
A second-tier formal certification roadmap exists separately.

Contribute

There are two ways to help: ask for analysis from your browser, or lend a computer to do the analysis.

Without hardware: request analysis

Every unsolved position in the explorer has a Request analysis button. Requests jump to the front of the worker queue, so pointing the search at a line you care about is one click.
Limits apply per visitor to keep the queue healthy.
Asking again buys a genuinely deeper search: 128M, 512M and then 2B nodes.
After that, a request queues up to 78 searches of 128M on the lines below the position, the best lines first.
Asking for a position somebody else already asked for joins their request instead of queueing a duplicate.

How requests are ordered, shared, moved to the front or withdrawn is on The queue.

Long searches and leases

A worker that takes a task holds a lease on it. A healthy worker keeps a multi-hour lease alive explicitly, so a deep task cannot be assigned twice.

API

Scripts can do the same through two endpoints, one to read and one to ask. Both speak FEN, return JSON and work without an account:

GET /atomicdb/api/query?fen=... returns the stored verdict, score and move list.
POST /atomicdb/api/request with fen queues analysis, taking exactly the path the explorer button takes.

Parameters, replies, error codes and the other endpoints are on the API page.

Run a worker

A worker is a small program that takes analysis tasks from this server, runs the engine on them and sends the results back. Every completed batch is credited to your username.

Create an account via the OpenBench registration (instant activation).
Make sure you have python3. The worker downloads the reference engine on first run (sha256 verified; Windows and Linux x86-64 prebuilts, for CPUs from about 2013 onwards).
Run these three commands, with your own user name and password:

curl -O https://belzedar.duckdns.org/atomicdb/engines/atomicdb_worker.py

pip install requests chess

python atomicdb_worker.py -U your_user -P your_pass -S https://belzedar.duckdns.org -T 8 --hash 1024

The worker is a single self-contained file. It also lives in the OpenBench repo under Client/ if you prefer git.

Options

Option	What it does
`-T`	Engine threads per task. Any number; it does not need to be a multiple of anything.
`--hash`	Engine hash (transposition table) in MB. See memory below.
`--syzygy dir1;dir2;dir3`	Use atomic Syzygy tablebases. Optional.
`--engine path/to/binary`	Use your own Atomic-Stockfish build. An engine given this way is never replaced.
`--no-auto-update`	Do not update the worker file. Only for a custom worker file you maintain on purpose.
`--no-engine-update`	Stay on the engine the worker started with until the next restart.

Memory

Memory does not grow with the node budget. The transposition table has a fixed size, so a 2B search uses the same RAM as a 128M one; it just runs longer.
About 1 GB of free RAM per engine instance is enough to handle anything. Budget roughly hash + 300 MB per engine instance.
A bigger table buys search quality on long runs (less overwriting of entries). If you can spare the RAM, run --hash 4096 or --hash 8192.

Updates

The worker checks the official HTTPS source for a new version at startup and between completed task batches. It validates the new file, keeps the previous version as a backup, and restarts itself without interrupting a search or an uncertain result submission.
Copies older than build 2026102001 need one manual download: that build changed how the worker restarts itself after an update, and older copies do not install it on their own. From that build onward, updates install themselves.
The downloaded engine is kept current too. While it runs, the worker checks for a newly published engine, downloads it next to the one in use, verifies its sha256, runs a short check search with it, and switches to it between tasks.

Tablebases

Tablebases are optional. Without them your worker is still fully valid; the engine simply searches every position itself.
If you have disk to spare, get the atomic Syzygy set from tablebase.lichess.ovh/tables/atomic/: 3-4-5 pieces is 1.3 GB, 6-piece WDL 91 GB, 6-piece DTZ 129 GB. Even 3-4-5 alone helps.
Add --syzygy dir1;dir2;dir3. The engine becomes tablebase-aware, and endgames it reaches are closed exactly without costing a single node.

Credits

Piece images: the cburnett set from lichess (CC BY-SA 3.0). Engine: Atomic-Stockfish. Rules oracle: pyffish (Fairy-Stockfish bindings).