Skip to content
Home » News » Guide of fastchess in linux running sprt

Guide of fastchess in linux running sprt

fastchess in linux

Installing FastChess on Ubuntu 20.04 LTS and Running an SPRT Test

1. Introduction

Reliable testing is the backbone of modern chess-engine development. When we wish to determine whether a new binary is genuinely stronger than a baseline, we require:

  • a robust tournament runner,
  • a reproducible environment, and
  • a well-understood statistical framework.

FastChess is a high-performance command-line tool designed precisely for this purpose: it orchestrates engine-versus-engine tournaments, supports concurrent games, reads both PGN and EPD opening books, and offers first-class support for Sequential Probability Ratio Tests (SPRT). (GitHub)

In this tutorial, we shall:

  • install FastChess from source on Ubuntu 20.04 LTS;
  • obtain and compile the Deepalienist chess engine from source (AVX2 and AVX2-PEXT builds); (GitHub)
  • prepare an opening suite in PGN format; and
  • launch an SPRT test comparing Deepalienist-2.10-181125-avx2 against Deepalienist-2.10-181125-avx2-pext.

The goal is that a technically minded user, even if not yet familiar with Linux, can follow the procedure and reproduce the testing environment without difficulty.

2. Prerequisites

2.1. Hardware assumptions

This guide assumes that you are working with:

  • a 64-bit x86_64 processor,
  • support for AVX2, and ideally
  • support for BMI2/PEXT (required for the AVX2-PEXT build).

On Ubuntu you can check this using:

lscpu | grep -i 'avx2\|bmi2'
  • If avx2 appears in the flags, AVX2 builds are supported.
  • If bmi2 appears, you may safely run PEXT-enabled binaries such as x86-64-avx2-pext. (GitHub)

2.2. Software assumptions

We assume:

  • Ubuntu 20.04 LTS with Internet access;
  • a user account with sudo privileges; and
  • basic familiarity with the terminal (changing directory, copying files, etc.).

All commands below use sudo where appropriate. If you are already operating as root on a VPS, you may omit sudo.

3. Updating the system and installing build tools

First, ensure that Ubuntu is up to date and that the essential compilation tools are present.

sudo apt update
sudo apt upgrade -y

Install Git and the standard GNU build toolchain (GCC, make, headers):

sudo apt install -y git build-essential

On Ubuntu 20.04 this will typically install GCC 9.x and the associated C++17-capable toolchain, which is sufficient for FastChess and Deepalienist. (GitHub)

4. Installing FastChess from source

4.1. Cloning the FastChess repository

FastChess is hosted on GitHub under the Disservin account. (GitHub)

From your home directory:

cd ~
git clone https://github.com/Disservin/fastchess.git
cd fastchess

This creates a folder ~/fastchess containing the source code and a Makefile.

4.2. Building the FastChess binary

The project provides a very straightforward build process. According to the official documentation, it is sufficient to run make -j (or make -j CXX=clang++ if you wish to use Clang). (GitHub)

make -j"$(nproc)"
  • $(nproc) automatically uses all available CPU cores during compilation.

This will generate a fastchess executable in the repository root.

4.3. Installing FastChess system-wide (optional but recommended)

To make fastchess available from any directory:

sudo make install

By default this installs:

  • the binary into /usr/local/bin/fastchess,
  • and the manual page (if generated) under /usr/local/share/man/man1/. (GitHub)

You can verify the installation simply by calling the executable without arguments:

fastchess

You should see a usage summary rather than an error such as “command not found”. (Note that FastChess does not necessarily provide a --version flag; lack of such an option does not indicate a faulty build.)

5. Obtaining and compiling Deepalienist

5.1. Cloning the Deepalienist repository

Deepalienist is an advanced open-source UCI chess engine hosted on GitHub. The src/ directory contains the full engine, and the documentation explicitly describes the recommended build targets for AVX2 and PEXT variants. (GitHub)

From your home directory:

cd ~
git clone https://github.com/jordiqui/Deepalienist.git
cd Deepalienist

Ensure that the clone completed successfully; you should see folders such as src, docs, config, and scripts.

5.2. Directory layout for engine binaries

It is wise to keep compiled engines in a predictable location, separate from their respective source trees. Here we will use:

mkdir -p ~/engines/deepalienist

We shall later copy the compiled binaries into this directory as:

  • Deepalienist-2.10-181125-avx2
  • Deepalienist-2.10-181125-avx2-pext

This consistent naming scheme simplifies FastChess command lines and log interpretation.

5.3. Compiling the AVX2 build

Change into the src directory of Deepalienist:

cd ~/Deepalienist/src

The README describes architecture-specific build targets such as x86-64-avx2 and x86-64-avx2-pext. (GitHub)

To compile the AVX2 variant with GCC:

make -j build ARCH=x86-64-avx2

The resulting binary, according to the documentation, will usually carry the project name and version (for example Deepalienist-2.10-181125). (GitHub)

You can confirm with:

ls

Look for Deepalienist-2.10-181125 (or a similarly named file).

Copy the AVX2 binary to your engines directory and assign a descriptive name:

cp ./Deepalienist-2.10-181125 \
   ~/engines/deepalienist/Deepalienist-2.10-181125-avx2

chmod +x ~/engines/deepalienist/Deepalienist-2.10-181125-avx2

5.4. Compiling the AVX2-PEXT build

Deepalienist provides dedicated architecture targets that enable PEXT support, adding -DUSE_PEXT and the appropriate -mbmi2 flags, and producing binaries with a -pext suffix. (GitHub)

From ~/Deepalienist/src:

make -j build ARCH=x86-64-avx2-pext

On Linux, this typically creates a binary named:

Deepalienist-2.10-181125-pext

Copy it to your engines directory under a clear name:

cp ./Deepalienist-2.10-181125-pext \
   ~/engines/deepalienist/Deepalienist-2.10-181125-avx2-pext

chmod +x ~/engines/deepalienist/Deepalienist-2.10-181125-avx2-pext

Important: The AVX2-PEXT binary requires hardware support for BMI2/PEXT. If your CPU does not provide these instructions, the binary may crash immediately upon start. Always verify with lscpu as described in Section 2.1.

5.5. Quick functional check with bench

Before involving FastChess, it is prudent to test that both binaries respond correctly to basic UCI commands.

From the engines directory:

cd ~/engines/deepalienist

./Deepalienist-2.10-181125-avx2       bench
./Deepalienist-2.10-181125-avx2-pext  bench

You should see Deepalienist running an internal benchmark and printing search statistics. If either binary fails here, resolve the compilation or hardware issue before proceeding.

6. Preparing the opening suite

High-quality regression testing requires a controlled set of starting positions. FastChess can read opening suites in both EPD and PGN formats; the official documentation explicitly encourages the use of an opening book. (GitHub)

Assume you have an opening suite named:

UHO_2022_8mvs_+110_+119.pgn

Create a directory for suites:

mkdir -p ~/suites

If the file is on your local machine, you can upload it via scp:

# On your local machine (replace USER and HOST accordingly)
scp /path/to/UHO_2022_8mvs_+110_+119.pgn \
    USER@HOST:~/suites/

On the Ubuntu 20.04 system, confirm its presence:

ls ~/suites
# Expect: UHO_2022_8mvs_+110_+119.pgn

FastChess will later index this file when constructing the round robin.

7. Running a short sanity test with FastChess

Before launching a lengthy SPRT campaign, it is wise to run a short fixed-length match to ensure that:

  • both engines initialise correctly under FastChess,
  • the opening suite is read without errors, and
  • there are no unexpected time losses or crashes.

7.1. Basic FastChess command structure

According to the FastChess README, a minimal example follows the pattern: (GitHub)

fastchess -engine cmd=Engine1 name=Engine1 \
          -engine cmd=Engine2 name=Engine2 \
          -each tc=10+0.1 \
          -rounds 200 \
          -repeat \
          -concurrency 4

We shall adapt this to Linux paths, add explicit UCI options, and lower the concurrency for a small 2-core VPS.

7.2. Short test command (e.g. 20 games)

From your home directory:

cd ~

fastchess \
  -engine name=DA2.10-avx2      cmd=./engines/deepalienist/Deepalienist-2.10-181125-avx2 \
  -engine name=DA2.10-avx2pext  cmd=./engines/deepalienist/Deepalienist-2.10-181125-avx2-pext \
  -openings file=./suites/UHO_2022_8mvs_+110_+119.pgn format=pgn order=random \
  -each proto=uci tc=10+0.1 option.Hash=128 option.Threads=1 \
  -rounds 10 \
  -repeat \
  -concurrency 1 \
  -pgnout notation=san file=DA2.10_avx2_vs_avx2pext_UHO2022_test.pgn \
  -log   file=DA2.10_avx2_vs_avx2pext_UHO2022_test.log

Let us briefly interpret the key options:

  • -engine name=... cmd=...
    Declares two UCI engines with explicit names and paths.
  • -openings file=... format=pgn order=random
    Points to the PGN opening suite and instructs FastChess to sample positions in random order.
  • -each proto=uci tc=10+0.1 option.Hash=128 option.Threads=1
    Configures common settings for both engines: UCI protocol, 10+0.1 time control, 128 MB hash, single thread.
  • -rounds 10 -repeat
    A “round” consists of the two engines playing a mini-match with colours reversed. Ten rounds thus yield twenty games (10×2).
  • -concurrency 1
    Only one game at a time. This is conservative and appropriate for a small dual-core VPS. On a larger machine, higher values (2,4,…) are appropriate.
  • -pgnout ... and -log ...
    Request a complete PGN file with SAN notation and a text log with engine and match statistics.

If this test completes without issues, you have validated the entire toolchain: binaries, book, time control, and logging.

8. Understanding SPRT in the context of engine testing

Before constructing the actual SPRT command line, it is worth briefly reviewing what SPRT is and why FastChess supports it.

8.1. Conceptual overview

The Sequential Probability Ratio Test (SPRT) is a statistical method for comparing two hypotheses:

  • H₀: The new engine is no stronger than the baseline (often Elo difference ≤ 0).
  • H₁: The new engine is stronger by at least some target value (e.g. +2.5 Elo).

Rather than fixing a predetermined number of games, SPRT evaluates the likelihood ratio after each game and stops early when the evidence is sufficiently strong for either H₀ or H₁, governed by error probabilities:

  • α: maximum acceptable probability of a false positive (accepting H₁ when H₀ is true),
  • β: maximum acceptable probability of a false negative (accepting H₀ when H₁ is false).

In practice, α and β are often set symmetrically at 0.05, mirroring your original batch setting:

set "ELO0=0"
set "ELO1=2.5"
set "ALPHA=0.05"
set "BETA=0.05"

The same values translate directly into FastChess’s -sprt option.

8.2. SPRT parameters in FastChess

FastChess exposes the SPRT configuration via a single compound option:

-sprt elo0=0 elo1=2.5 alpha=0.05 beta=0.05

These correspond exactly to the conceptual parameters above:

  • elo0 → null hypothesis Elo difference,
  • elo1 → alternative hypothesis Elo difference,
  • alpha → Type I error probability,
  • beta → Type II error probability.

When an SPRT test is active, the -rounds parameter becomes an upper bound rather than a target: the test will terminate early if the SPRT reaches a decision before exhausting the specified rounds. FastChess’s issue tracker and documentation make frequent reference to its SPRT implementation and its numerical details. (GitHub)

9. Launching an SPRT match with Deepalienist and FastChess

We now turn the short fixed-length test into a full SPRT campaign.

9.1. Creating a reusable shell script

For convenience and reproducibility, we encapsulate the FastChess invocation in a shell script in the home directory. This also makes it easier to restart the same configuration later.

From your home directory:

cd ~

cat > run_DA2.10_UHO2022_10+0.1_sprt.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail

cd "$HOME"

fastchess \
  -engine name=DA2.10-avx2      cmd=./engines/deepalienist/Deepalienist-2.10-181125-avx2 \
  -engine name=DA2.10-avx2pext  cmd=./engines/deepalienist/Deepalienist-2.10-181125-avx2-pext \
  -openings file=./suites/UHO_2022_8mvs_+110_+119.pgn format=pgn order=random \
  -each proto=uci tc=10+0.1 option.Hash=128 option.Threads=1 \
  -rounds 400000 \
  -repeat \
  -concurrency 1 \
  -draw movenumber=34 movecount=8 score=20 \
  -resign movecount=3 score=600 \
  -sprt elo0=0 elo1=2.5 alpha=0.05 beta=0.05 \
  -ratinginterval 10 \
  -scoreinterval 10 \
  -report penta=true \
  -pgnout notation=san file=DA2.10_avx2_vs_avx2pext_UHO2022_10+0.1_sprt.pgn \
  -log   file=DA2.10_avx2_vs_avx2pext_UHO2022_10+0.1_sprt.log
EOF

chmod +x ./run_DA2.10_UHO2022_10+0.1_sprt.sh

Key additional options introduced here:

  • -rounds 400000
    A very high upper bound: SPRT is expected to terminate long before this limit is reached.
  • -draw movenumber=34 movecount=8 score=20
    Early draw adjudication: if the evaluation stays within ±20 centipawns for a specified window of moves (starting at move 34, over 8 moves), the game is declared a draw. This can significantly reduce test time in balanced positions.
  • -resign movecount=3 score=600
    Resignation behaviour: if an engine’s evaluation remains below −600 centipawns for 3 consecutive moves, the game is adjudicated as a loss.
  • -ratinginterval 10 and -scoreinterval 10
    FastChess will periodically output interim Elo and score statistics every 10 games.
  • -report penta=true
    Requests pentanomial reporting, which can be advantageous for precise Elo estimation with modern SPRT test suites.

9.2. Starting the SPRT test

Simply run:

./run_DA2.10_UHO2022_10+0.1_sprt.sh

You should see output similar to:

Indexing opening suite...
Started game 1 of 800000 (DA2.10-avx2 vs DA2.10-avx2pext)
Started game 2 of 800000 (DA2.10-avx2pext vs DA2.10-avx2)
...

Remember that one round consists of two games (both colour permutations), hence the “of 800000” when -rounds 400000 and -repeat are active.

9.3. Monitoring progress

Open a second terminal (or SSH session) and monitor the log in real time:

cd ~
tail -f DA2.10_avx2_vs_avx2pext_UHO2022_10+0.1_sprt.log

You will see a stream of updates including:

  • game numbers,
  • win/draw/loss counts,
  • Elo estimates, and
  • SPRT-related statistics (e.g. LLR, current hypothesis).

To exit tail -f, press Ctrl + C.

At any time, you may also check the number of games already stored in the PGN file:

grep -E "\[Result" DA2.10_avx2_vs_avx2pext_UHO2022_10+0.1_sprt.pgn | wc -l

This returns the count of completed games (each game has a Result tag in PGN).

10. Interpreting the results

Once the SPRT terminates, FastChess will print a final summary in the log file outlining:

  • the observed win/draw/loss statistics,
  • the estimated Elo difference between the AVX2 and AVX2-PEXT binaries,
  • and the SPRT conclusion (e.g. accepting H₁ that the PEXT build is at least 2.5 Elo stronger, or accepting H₀ that it is not).

The Deepalienist repository itself provides additional guidance on how to interpret SPRT outputs and how they fit into a disciplined regression-testing workflow. (GitHub)

For more advanced workflows, results from FastChess can be fed into Elo estimation tools or plotted over time. At this stage, however, the essential question is binary:

Is the PEXT-enabled binary statistically stronger than the plain AVX2 build under this test protocol?

If SPRT accepts H₁, you have strong evidence (at the chosen α and β) that the AVX2-PEXT build provides a small but real Elo gain on your specific hardware and time control. If SPRT accepts H₀, the gain is not statistically supported and you may treat the two builds as effectively equal for practical purposes, at least under this testing configuration.

11. Variations and extensions

Once the basic pipeline is in place, many refinements are possible:

  • Different time controls
    You may change tc=10+0.1 to bullet controls such as 3+0.01 or rapid/blitz controls such as 20+0.2 to mimic specific rating lists or server environments.
  • Larger hash
    For serious tests on strong hardware, increasing option.Hash to 512 or 1024 can be reasonable, provided sufficient system memory is available.
  • Multiple threads
    For multi-core systems, increasing option.Threads and appropriately scaling -concurrency allows you to exploit hardware parallelism while avoiding oversubscription. For example, with 16 physical cores you might use Threads=1 and -concurrency 16, or Threads=2 and -concurrency 8.
  • Alternative opening books
    You can swap UHO_2022_8mvs_+110_+119.pgn for any other curated PGN or EPD suite. The format= and order= parameters can be adjusted accordingly (e.g. format=epd).
  • CuteChess-style output
    FastChess supports a -output cutechess mode to approximate CuteChess logs, useful if you have existing tooling that expects that format.
  • Resuming interrupted runs
    Advanced usage includes configuration files and resumption of interrupted tests (e.g. after a reboot), via FastChess’s -config mechanisms discussed in community forums and its manual.

12. Conclusion

This tutorial has outlined a complete, reproducible workflow for installing FastChess on Ubuntu 20.04 LTS and running an SPRT test between two Deepalienist binaries—one AVX2 and one AVX2-PEXT—using a curated PGN opening suite.

We have:

  1. Updated the system and installed the GNU toolchain.
  2. Cloned and built FastChess from its official GitHub repository.
  3. Cloned the Deepalienist engine, compiled AVX2 and AVX2-PEXT variants following the project’s documented architecture targets.
  4. Uploaded and prepared a PGN opening suite suitable for robust engine testing.
  5. Run a short fixed-length match to verify that everything functions correctly.
  6. Configured and executed a full SPRT campaign with well-defined hypotheses and error probabilities.

With this infrastructure in place, you can systematically evaluate future Deepalienist versions—or indeed any other UCI engine—under statistically rigorous conditions. The pipeline is intentionally modular: engines, books, time controls, and SPRT thresholds are all easily swapped or tuned, while the underlying methodology remains stable.

Finally, it is important to remember that all results are hardware-dependent. An Elo gain observed on a powerful AVX2/BMI2 server may not replicate on older CPUs or on devices with fewer cores and smaller caches. For publishing rating lists or making release decisions, one should therefore document not only the test parameters and SPRT settings but also the hardware profile on which they were obtained.

Jorge Ruiz

Jorge Ruiz

Filólogo y amante de la antropología social africana

SÍGUEME
Tags:

Leave a Reply

Your email address will not be published. Required fields are marked *