Crate cozy_chess

Crate cozy_chess 

Source
Expand description

§cozy-chess

§Rust Chess and Chess960 move generation library

crates.io ko-fi lgbtq+ friendly trans rights

cozy-chess is a Chess and Chess960 (Fischer Random Chess) move generation library written in Rust that aims to provide competitive move generation performance. It is largely inspired by Jordan Bray’s neat chess library. cozy-chess aims to be a safer alternative to chess that maintains correctness while providing similar performance.

§Overview

  • no_std compatible
  • Supports Chess, Chess960/FRC, and Double Chess960/DFRC
  • Strongly-typed API that makes heavy use of newtypes to avoid errors
  • Performant legal move generation suitable for use in a chess engine
    • Implements fixed shift fancy black magic bitboards
    • Optionally implements PEXT bitboards based on the BMI2 intrinsic
    • Flexible API produces moves in bulk for optional bulk filtering
  • Efficient bitboard-based board representation
  • Incrementally updated zobrist hash for quickly obtaining a hash of a board

§Crate features

  • std: Enable features that require std. Currently only used for the Error trait.
  • pext: Enable PEXT bitboards.

§A note on CPU features and performance

By default, Rust binaries target a baseline CPU to ensure maximum compatibility at the cost of performance. cozy-chess benefits significantly from features present in modern CPUs. For maximum performance, the target CPU can instead be set to native to use features supported by the machine running the build. Alternatively, the target CPU can be set to x86-64-v3, which will produce binaries that run on most modern CPUs. The target CPU may be changed by adding -C target-cpu=<CPU> to RUSTFLAGS.

PEXT bitboards are a faster variant of the magic bitboard algorithm used by cozy-chess. PEXT bitboards rely on an intrinsic introduced in the BMI2 CPU extension. However, it is not enabled by default, as PEXT bitboards are slower on AMD CPUs prior to Zen 3, which implement PEXT with microcode. PEXT bitboards can be enabled through the pext feature.

§A note on UCI parsing

In order to support Chess960, cozy-chess uses a king-captures-rook castling notation incompatible with the standard castling representation used by the UCI protocol. This is a common use case, so the cozy_chess::util module provides helpers that automatically parse and convert between the formats.

§Examples

§Basic example

// Start position
let board = Board::default();
let mut move_list = Vec::new();
board.generate_moves(|moves| {
    // Unpack dense move set into move list
    move_list.extend(moves);
    false
});
assert_eq!(move_list.len(), 20);

§Get capture moves in bulk

// Parse position from FEN
let board = "r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1"
    .parse::<Board>()
    .unwrap();

let mut total_moves = 0;
let mut total_captures = 0;

let enemy_pieces = board.colors(!board.side_to_move());
board.generate_moves(|moves| {
    let mut captures = moves.clone();
    // Bitmask to efficiently get all captures set-wise.
    // Excluding en passant square for convenience.
    captures.to &= enemy_pieces;

    total_moves += moves.len();
    total_captures += captures.len();
    false
});

assert_eq!(total_moves, 48);
assert_eq!(total_captures, 8);

§Perft example

A perft implementation exists in examples/perft.rs:

$ cargo run --release --example perft -- 7
   Compiling cozy-chess v0.3.0
    Finished release [optimized] target(s) in 6.37s
     Running `target\release\examples\perft.exe 7`
3195901860 nodes in 10.05s (318045465 nps)

§Changelog

§v0.3.4

§Added
  • Added helper methods for handling UCI moves.
  • Added Square::relative_to to get a square relative to some color.

§v0.3.3

§Added
  • Added setters for the halfmove clock and fullmove number fields.
§Fixed
  • Fixed checkmate not taking precedence over 50 move rule draw.
  • Fixed possible overflows on halfmove clock and fullmove number.

§v0.3.2

§Fixed
  • Fixed bug where en passant was not correctly validated when parsing and building Boards.

§v0.3.1

§Fixed
  • Fixed bug where Board::is_legal said castles while in check were legal.

§v0.3.0

§Added
  • Added methods for obtaining Chess960 start positions from their Scharnagl number.
  • Added PEXT bitboards using the BMI2 PEXT intrinsic. Potentially faster than the default algorithm. Enable using the pext feature.
  • Added Board::hash_without_ep method for fast equivalence checks excluding the en passant square.
  • Added Board::same_position to check if two boards are equivalent under FIDE rules.
  • Added Board::colored_pieces, a shorthand for board.colors(color) & board.pieces(piece).
  • Added BitBoard::is_subset, BitBoard::is_superset, and BitBoard::is_disjoint.
§Changed (breaking)
  • BitBoards now operate in a more set-wise manner instead of acting like a u64. Bit operators changed to match set operators.
  • BitBoard::popcnt renamed to BitBoard::len for consistency with other data structures.
  • BoardBuilder’s fullmove_number field changed to a u16 for usability reasons.
  • Board’s FromStr implementation now parses both FEN and Shredder FEN.
§Removed (breaking)
  • BitBoard no longer implements Iterator directly.
  • Sliding move functions are no longer const by default; Use the const variants if required.
  • Unnecessary “try” variants on Board removed; The risk of panicking is accepted when *_unchecked methods are called.
§Fixed
  • Overflow bug in Square::try_offset fixed.
  • FenParseError is no longer unnameable.
  • Fixed incorrect errors being returned in FEN parsing.
  • Fixed some errors not being produced in FEN parsing.

Modules§

util
Additional common utilities

Macros§

bitboard
BitBoard literal macro.

Structs§

BitBoard
A bitboard. A bitboard is an ordered set of squares.
BitBoardIter
An iterator over the squares of a bitboard.
BitBoardSubsetIter
An iterator over the subsets of a bitboard.
Board
A chessboard.
BoardBuilder
A board builder to manipulate arbitrary boards.
CastleRights
Castling rights.
ColorParseError
The value was not a valid Color.
FileParseError
The value was not a valid File.
IllegalMoveError
An error returned when the move played was illegal.
Move
A chess move.
MoveParseError
The value was not a valid Move.
PieceMoves
A compact structure representing multiple moves for a piece on the board. Iterate it to unpack its moves.
PieceMovesIter
Iterator over the moves in a PieceMoves instance.
PieceParseError
The value was not a valid Piece.
RankParseError
The value was not a valid Rank.
SquareParseError
The value was not a valid Square.

Enums§

BoardBuilderError
An error while building a board.
Color
A side to move.
FenParseError
An error while parsing the FEN.
File
A file on a chessboard.
GameStatus
The current state of the game.
Piece
A chess piece. Pieces are ordered by approximate material value.
Rank
A rank on a chessboard.
Square
A square on a chessboard. Squares are ordered in rank-major order (A1, B1, C1, … H8).

Functions§

get_between_rays
Get all squares between two squares, if reachable via a ray.
get_bishop_moves
Get the moves for a bishop on some square. See get_bishop_moves_const for a significantly slower const variant.
get_bishop_moves_const
Significantly slower const version of get_bishop_moves.
get_bishop_rays
Get the rays for a bishop on some square.
get_king_moves
Get the king moves for a king on some square.
get_knight_moves
Get the knight moves for a knight on some square.
get_line_rays
Get a ray on the board that passes through both squares, if it exists.
get_pawn_attacks
Get the pawn attacks for a pawn on some square.
get_pawn_quiets
Get the pawn forward moves/non-captures for a pawn of some color on some square.
get_rook_moves
Get the moves for a rook on some square. See get_rook_moves_const for a significantly slower const variant.
get_rook_moves_const
Significantly slower const version of get_rook_moves.
get_rook_rays
Get the rays for a rook on some square.