chore: Significantly improve docs, refactor some code and overhaul infra

kirillbobyrev · May 21, 2024 · 5fdba74 · 5fdba74
1 parent 258044e
commit 5fdba74
Show file tree

Hide file tree

Showing 28 changed files with 158 additions and 133 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -37,17 +37,8 @@ jobs:
           profile: minimal
           toolchain: ${{ matrix.toolchain }}
           override: true
-      - uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/bin/
-            ~/.cargo/registry/index/
-            ~/.cargo/registry/cache/
-            ~/.cargo/git/db/
-            target/
-          key: ${{ runner.os }}-${{ matrix.toolchain }}-cargo-${{ hashFiles('**/Cargo.lock') }}
       - name: Build the project
         uses: actions-rs/cargo@v1
         with:
           command: build
-          args: --release --all-features
+          args: --release
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -16,15 +16,6 @@ jobs:
           toolchain: nightly
           override: true
           components: rustfmt, clippy
-      - uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/bin/
-            ~/.cargo/registry/index/
-            ~/.cargo/registry/cache/
-            ~/.cargo/git/db/
-            target/
-          key: ${{ runner.os }}-nightly-cargo-${{ hashFiles('**/Cargo.lock') }}
       - name: Cargo fmt
         uses: actions-rs/cargo@v1
         with:
@@ -34,6 +25,6 @@ jobs:
         uses: actions-rs/clippy-check@v1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-          args: --all-features -- --deny clippy::all --deny clippy::pedantic
+          args: --all-features
       - name: typos-action
         uses: crate-ci/typos@v1.21.0
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -31,20 +31,7 @@ jobs:
           profile: minimal
           toolchain: ${{ matrix.toolchain }}
           override: true
-      - uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/bin/
-            ~/.cargo/registry/index/
-            ~/.cargo/registry/cache/
-            ~/.cargo/git/db/
-            target/
-          key: ${{ runner.os }}-${{ matrix.toolchain }}-cargo-${{ hashFiles('**/Cargo.lock') }}
-      - name: Run cargo test
-        uses: actions-rs/cargo@v1
-        with:
-          command: test
-      # Using -- --ignored is not possible with actions-rs/cargo, run plain
-      # cargo instead.
-      - name: Run expensive testts
+      - name: Run basic tests
+        run: cargo test --release
+      - name: Run expensive tests
         run: cargo test --release -- --ignored
diff --git a/.ignore b/.ignore
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -1,12 +1,11 @@
 {
   "recommendations": [
-    "bungcip.better-toml",
+    "tamasfe.even-better-toml",
     "davidanson.vscode-markdownlint",
     "matklad.rust-analyzer",
     "redhat.vscode-yaml",
     "serayuzgur.crates",
     "streetsidesoftware.code-spell-checker",
     "yzhang.markdown-all-in-one",
-    "editorconfig.editorconfig"
   ]
 }
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -4,15 +4,59 @@ This document describes high-level architecture of Pabi. If you want to get
 familiar with the code and understand the project structure, this is a great
 starting point.
 
-## Design considerations
+## Scope
+
+Implementing a *general-purpose* chess engine that would truly excel in
+different domains, such as playing with humans, being able to adjust the
+strength, providing the best possible analysis for a position when given a lot
+of time and, finally, playing well against other engines is an enormous task,
+especially for one person. Therefore, it's crucial to choose the right scope and
+design the engine with chosen limitations in mind.
+
+Pabi chooses to be the best possible version of an engine that does well against
+other chess engines in online tournaments. That means that it will prioritize
+performance under the constraints put by the rules and environments of such
+tournaments. Most important tournament organizers are
+[TCEC](https://tcec-chess.com/) and
+[CCCC](https://www.chess.com/computer-chess-championship), and the most
+prominent rating to date is [CCRL](https://computerchess.org.uk/ccrl/). The
+first goal is reaching 3000 ELO on the rating lists that are accepted by the
+organizers of these tournaments.
+
+Most of the competitions are in relatively fast time controls (Blitz, Bullet,
+Rapid) with some exceptions in relatively short classical formats. These are the
+[CCRL rules](https://computerchess.org.uk/ccrl/404/about.html) and [TCEC
+rules](https://wiki.chessdom.org/Rules). In both rule sets the engines are given
+opening books selected by the organizers and unknown to the participants, and
+the engines start the game in pre-determined positions which creates space for
+unbalance leading to decisive results.
+
+In all cases, the testing environment's CPU is of x86_64 architecture, which is
+very important because of PEXT and PDEP instructions that significantly increase
+the performance of move generators. Also, the processors have multiple cores,
+sometimes there as many as 256 cores as in CCC22:
+
+```
+CPUs | 2 x AMD EPYC 7H12
+GPU | 2x A100 (40 GB GPU memory)
+Cores | 256 cores (128 physical)
+RAM | 512GB DIMM DDR4 2933 MHz (0.3 ns)
+SSD | 2x Micron 5210 MTFD (2TB) in RAID1
+OS | CentOS 8
+```
+
+This requires the engine to be very good at utilizing multi-threading.
+
+Other design choices are deliberate focus on performance over most things
+(except simplicity and clarity), such as error recovery (there should be minimal
+one: if the error happened and the engine can reject the input, it will reject
+the input and continue working) and support for arcane environments.
 
 ## Recipes
 
-### Building
-
-### Testing
-
-### Fuzzing
+Most commands for development, building the engine, testing, checking for errors
+and fuzzing it are supported as [just](https://github.com/casey/just) recipes.
+See [justfile](/justfile) for a complete list of frequently used commands.
 
 ## Code map
 

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 # Pabi
 
 [![Codecov](https://codecov.io/gh/kirillbobyrev/pabi/branch/main/graph/badge.svg)](https://codecov.io/gh/kirillbobyrev/pabi)
-[![Lines of Code](https://tokei.rs/b1/github/kirillbobyrev/pabi)](https://github.com/kirillbobyrev/pabi/tree/main/src)
+[![Lines of Code](https://tokei.rs/b1/github/kirillbobyrev/pabi?type=Rust)](https://github.com/kirillbobyrev/pabi/tree/main/src)
 
 [![Build](https://github.com/kirillbobyrev/pabi/actions/workflows/build.yml/badge.svg)](https://github.com/kirillbobyrev/pabi/actions/workflows/build.yml)
 [![Test Suite](https://github.com/kirillbobyrev/pabi/actions/workflows/test.yml/badge.svg)](https://github.com/kirillbobyrev/pabi/actions/workflows/test.yml)
@@ -15,6 +15,9 @@ itself is implemented in this repository, training and development of the Neural
 Network for position evaluation is in
 [kirillbobyrev/pabi-brain](https://github.com/kirillbobyrev/pabi-brain).
 
+For architecture, design and development process overview, please see
+[CONTRIBUTING.md](/CONTRIBUTING.md).
+
 ## Goals
 
 Pabi is inspired by existing Chess and Go engines (mainly [AlphaGo], [lc0],

diff --git a/fuzz/Cargo.lock b/fuzz/Cargo.lock
diff --git a/justfile b/justfile
@@ -0,0 +1,41 @@
+# This is a collection of commonly used recipes for development. Most of them
+# are wrappers around Cargo and Cargo extensions with certain setup.
+
+# Enable x86_64 features that are required for maximum performance.
+compile_flags := "RUSTFLAGS='-C target-feature=+avx2,+fma,+bmi1,+bmi2'"
+
+build:
+  {{ compile_flags }} cargo build --profile=fast
+
+# Runs the engine and enters UCI mode.
+run:
+  {{ compile_flags}} cargo run --profile=fast
+
+# Checks the code for bad formatting, errors and warnings.
+lint:
+  cargo +nightly fmt --all
+  cargo +nightly clippy --all-features --fix --allow-staged
+  typos
+
+# Run most tests that are fast and are run by default.
+test_basic:
+  cargo test
+
+# Run tests that are slow and are not run by default.
+test_slow:
+  cargo test -- --ignored
+
+# Run all tests.
+test: test_basic test_slow
+
+bench:
+  {{ compile_flags }} cargo bench --profile=fast
+
+# Lists all fuzzing targets that can be used as inputs for fuzz command.
+list_fuzz_targets:
+  cd fuzz
+  cargo +nightly fuzz list
+
+fuzz target:
+  cd fuzz
+  {{ compile_flags }} cargo +nightly fuzz run {{ target }}
diff --git a/scripts/test.sh b/scripts/test.sh
diff --git a/src/chess/core.rs b/src/chess/core.rs
@@ -52,9 +52,7 @@ impl Move {
 }
 
 impl fmt::Display for Move {
-    /// Serializes a move in [UCI format].
-    ///
-    /// [UCI format]: http://wbec-ridderkerk.nl/html/UCIProtocol.html
+    /// Serializes a move in UCI format (used by [`pabi::uci`]).
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "{}{}", self.from, self.to)?;
         if let Some(promotion) = self.promotion {

diff --git a/src/chess.rs → src/chess/mod.rs b/src/chess.rs → src/chess/mod.rs
diff --git a/src/chess/position.rs b/src/chess/position.rs
@@ -46,7 +46,7 @@ use crate::chess::core::{
 // TODO: Store Zobrist hash, possibly other info.
 #[derive(Clone)]
 pub struct Position {
-    board: Board,
+    pub(crate) board: Board,
     castling: CastleRights,
     side_to_move: Player,
     /// [Halfmove Clock][^ply] keeps track of the number of (half-)moves

diff --git a/src/engine.rs b/src/engine.rs
diff --git a/src/search/.gitkeep → src/engine/mod.rs b/src/search/.gitkeep → src/engine/mod.rs
diff --git a/src/evaluation.rs b/src/evaluation.rs
diff --git a/src/evaluation/material.rs b/src/evaluation/material.rs
@@ -0,0 +1,13 @@
+use crate::chess::position::Position;
+
+const PAWN_VALUE: f32 = 1.;
+const KNIGHT_VALUE: f32 = 3.;
+const BISHOP_VALUE: f32 = 3.;
+const ROOK_VALUE: f32 = 5.;
+const QUEEN_VALUE: f32 = 9.;
+
+fn material_advantage(position: &Position) -> f32 {
+    0.
+}
+
+// TODO: Test.
diff --git a/src/evaluation/mod.rs b/src/evaluation/mod.rs
@@ -0,0 +1 @@
+mod material;
diff --git a/src/evaluation/trivial.rs b/src/evaluation/trivial.rs
diff --git a/src/interface/mod.rs b/src/interface/mod.rs
@@ -0,0 +1 @@
+pub mod uci;
diff --git a/src/uci.rs → src/interface/uci.rs b/src/uci.rs → src/interface/uci.rs
@@ -1,5 +1,6 @@
-//! Implementation of [Universal Chess Interface] (UCI) protocol for communication
-//! between the engine and the UCI client (e.g. GUI, tournament runner).
+//! Implementation of [Universal Chess Interface] (UCI) protocol for
+//! communication between the engine and the UCI client (e.g. GUI, tournament
+//! runner).
 //!
 //! The implementation here does not aim to be complete and exhaustive, because
 //! the main goal is to make the engine work in relatively simple setups, making
@@ -14,7 +15,6 @@ use crate::VERSION;
 
 /// Reads UCI commands from the input stream and executes them accordingly while
 /// writing the responses to the output stream.
-///
 // TODO: Document the expected behavior.
 // > The engine must always be able to process input from stdin, even while
 // > thinking.
@@ -128,7 +128,7 @@ pub fn run_loop(input: &mut impl BufRead, output: &mut impl Write) {
                 // This is practically no-op for now, maybe always. Not sure
                 // what should change when the new game is started.
             },
-            // position [fen <fenstring> | startpos ]  moves <move1> .... <movei>
+            // position [fen <fenstring> | startpos ]  moves <move1> .... <move_i>
             //
             // Set up the position described in `fenstring` on the internal board and
             // play the moves on the internal chess board.