A perft debugger. Compare your chess engine to Stockfish and quickly find
discrepancies in move generation.
When debugging a chess engine, it is common to compare its move generation to a
known-good engine using the results of the perft function, which
counts all of the nodes at some given depth from some starting position. Using
these results, one can quickly isolate the problematic subtrees and figure out
where the move generation differs between the two engines.
Instead of comparing the results and walking the tree manually, I use and
maintain perftree, a semi-automatic debugger that does that hard work for
you. It can keep track of where you are in the game tree, evaluate the perft
function at the current position, and compare the results automatically,
highlighting the differences so they are easy to pick out.
perftree uses Stockfish, a well-known engine used widely throughout the chess
community, as a trusted source of perft results. Download and install
Stockfish if you haven't already, and make sure you can run it
from the command line with the command stockfish.
Install the perftree program from the crates.io repository with cargo:
cargo install perftree
perftree requires some way to invoke the perft function on your chess
engine. Currently, it expects the user to provide a script, which will be
invoked like this:
./your-perft.sh "$depth" "$fen" "$moves"
where
$depth is the maximum depth of the evaluation,
$fen is the Forsyth-Edwards Notation string of some base position,
$moves is an optional space-separated list of moves from the base position
to the position to be evaluated, where each move is formatted as
$source$target$promotion, e.g. e2e4 or a7b8Q.
The script is expected to output the results of the perft function to standard output, with the following format:
For each move available at the current position, print the move and the number of nodes at the given depth which are an ancestor of that move, separated by whitespace.
After the list of moves, print a blank line.
Finally, print the total node count on its own line.
For example, this is what the depth-3 perft of the starting position should look like:
``` $ ./your-perft.sh 3 "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1" a2a3 380 b2b3 420 c2c3 420 d2d3 539 e2e3 599 f2f3 380 g2g3 420 h2h3 380 a2a4 420 b2b4 421 c2c4 441 d2d4 560 e2e4 600 f2f4 401 g2g4 421 h2h4 420 b1c3 440 g1h3 400 b1a3 400 g1f3 440
8902 ```
Run perftree from the commandline, and pass the script path as the first
argument:
bash
perftree ./your-script.sh
perftree understands the following commands:
fen [new_fen] - Set the FEN string of the root node, and clears the move
list. When new_fen is not provided, the current FEN string will be printed
instead.
moves [new_moves ...] - Set the move list. When new_moves is not
provided, the current move list will be printed instead.
depth [new_depth] - Set the max depth for perft. When new_depth is not
provided, the current depth will be printed instead.
root - Clears the move list, effectively changing to the root node of the
game tree.
child|move <move> - Pushes the given move onto the move list, effectively
changing to the child node identified by the given move in the current state.
parent|unmove - Pops a move from the move list, effectively changing to the
parent node of the current state.
diff - Calculates and outputs a diff of the perft results for the current
node. Your results will be on the left, and Stockfish will be on the right.
A missing number means that the move did not exist in the output from the
corresponding engine.
exit|quit - Exits the program.