README.md

Sporkfish

Sporkfish is a Python-based chess engine. Chess programming techniques, although numerous, are not always well-documented. This project aims to bridge that gap by offering clear, working, and accessible code, providing a resource for developers interested in understanding and implementing chess engine algorithms.

---

Setup

See any of the following sections to quickly setup your development environment.

• Using DevContainer with VSCode* recommended
• Using DevContainer with PyCharm
• Using Github Codespace
• Using native Docker

Using DevContainer with VSCode

Prerequisites:

• VSCode
• Docker Desktop

Instructions:

1. Make sure Docker Desktop is up and running.
2. Open up the Command Palette and run Dev Containers: Rebuild Container
3. The window should reload and you will see [Dev Container] in the URL bar as well as on the status bar bottom left of the window to indicate your setup is complete.

Using DevContainer with PyCharm

Prerequisites:

• PyCharm
• Docker Desktop

Instructions:

#TODO - Please see jetbrains docs, PyCharm setup is similar to VSCode

https://www.jetbrains.com/help/pycharm/connect-to-devcontainer.html

Using Github Codespace

Prerequisites:

• VSCode* optional

Instructions:

1. In this Github repository, click on the Code dropdown, select Codespace and click Create.
2. Confirm codespace settings, for Machine type select 2-core (this can be changed later if you require more power).

An active internet connection will be required for this. This will also use up your monthly allowance for Github codespace.

Using native Docker

Prerequisites:

• Docker Desktop

After cloning the repository, from the root directory, run:

docker pull kylchiu/sporkfish-dev:latest
docker build -t kylchiu/sporkfish-dev:latest .
docker run -it kylchiu/sporkfish-dev:latest

This generates an interactive bash shell for you to run the program in.

Usage

Lichess

Check out the bot on lichess here! To run the bot, create a file in the root directory named api_token.txt. Add your Lichess bot API token. Then run:

python3 -O main.py

Once you create a game via your bot account, the bot will automatically play. We currently do not support simultaneous games.

---

Principles

• Functional library: encourage free functions whilst avoiding mutable data unless the task specifically and inherently demands it (e.g. statistics, transposition table, board state).
• Well documented: classes should always have docstrings. Where the code is complex, additional inline comments should be made.

---

Features

Search:

• Negamax with fail-soft alpha-beta pruning
• Principal variation search
• Quiescence search
• Iterative deepening
• Null move pruning
• Futility pruning
• Delta pruning
• Aspiration windows
• Transposition tables with Zobrist hashing
• PolyGlot opening book
• Syzygy endgame tablebases

Move ordering:

• MVV-LVA move ordering

Evaluation:

• PeSTO

Communication:

• UCI

---

Resources

Engines

• cpw-engine
• Black Marlin
• Theodora
• black_numba

References

• Some techniques
• Engine improvement tier list
• Explaining beta-cutoff

Video (Youtube) Resources - beginner friendly

• Gentle introduction to how to set up a chess bot by Sebastian Lague
• How to improve a chess bot by Sebastian Lague
• Introduction to Minimax and Alpha-Beta Pruning:
  • by Sebastian Lague
  • by MIT OpenCourseWare
• Iterative Deepening Search:
  • by John Levine - in context of DFS
  • by Chess Programming - in the context of chess programming

---

For developers

Run Tests

To run all tests (excluding slow tests):

python3 -m pytest -v

You may also run a specific test class or function, e.g.:

python3 -m pytest tests/test_searcher.py::TestMvvLvaHeuristic -sv

Slow tests are not run on CI. Developers should run these before raising PRs by doing (this can be very slow, so please be patient):

python3 -m pytest -sv --runslow

Sphinx auto docstring generation (with Github Copilot and devcontainer)

This may or may not work depending if Copilot is happy on that day. Simply ask Copilot to generate your class with Sphinx docstrings. If that does not work, you could try:

1. Implement your class or function with type hints.
2. Add a template Sphinx docstring at the class level, i.e. above __init__ function. This can be done using Ctrl + Shift + 2 (Windows, Linux) or Command + Shift + 2 (Mac). Add ":param:" in your string if it isn't auto generated.
3. Using the Command Pallete, select "Github Copilot: Generate Docs" while your text cursor is inside the template Sphinx docstring. It should auto generate Sphinx docs for the entire class/function.

---