evaluate_game: Analyze a chess game

In dryguy/rbitr: Arbiter: One who ensures adherence to the rules and laws of chess

Analyze a chess game

Description

Chess games are analyzed using a UCI compatible chess engine.

Usage

evaluate_game(
  movetext,
  engine_path,
  limiter,
  limit,
  n_cpus = 1L,
  n_pv = 1L,
  mute = TRUE,
  hash_size = NULL
)

Arguments

movetext	A single-element character vector containing a sequence of moves in standard algebraic notation (SAN).
engine_path	A single-element character vector of the path to a UCI compatible chess engine.
limiter	A single-element character vector indicating the desired mode of search termination. Allowed values are 'depth' (to search a fixed number of plies), 'nodes' (to search a fixed number of nodes), and 'movetime' (to search a fixed number of milliseconds).
limit	A single-element integer vector of the desired search depth (# of plies), search nodes (# of nodes), or search time (# of milliseconds).
n_cpus	(Default = 1) A single-element integer vector of the number of cpus to use.
n_pv	(Default = 1) A single-element integer vector of the desired number of principal variations.
mute	(Default = TRUE) A single-element boolean vector indicating whether to display progress.
hash_size	(Default = NULL) A single-element integer vector of the desired hash size, in MB.

Details

The function evaluate_game() passes game positions to an external UCI compatible chess engine, which must be supplied by the user. The path to the engine's executable file is given by the engine_path parameter. The number of CPU's to devote to the analysis is determined by the n_cpus parameter.

The game to be analyzed should be in a PGN-compatible format, that is, moves should be in standard algebraic notation (SAN), and any comments, annotations, or variations should comply with the PGN specification. If variations are present, they will not be analyzed. The game is passed into evaluate_game() as a single-element character vector via the movetext parameter. The movetext is typically obtained from get_pgn(), where it would be found in the $Movetext column of get_pgn()'s output.

The number of principal variations to be analyzed is set using the n_pv parameter, while the depth of analysis is controlled by choosing a UCI command to set the criteria for search termination as either 'depth' (to search a fixed number of plies), 'nodes' (to search a fixed number of positions), or 'movetime' (to search a fixed number of milliseconds). The selection is controlled by the limiter and limit parameters. Note that the values apply to each position analyzed. For example, if the game has 80 plies, and 'movetime' is set to 1000 milliseconds, the analysis will take 80 seconds.

Value

A list containing character vectors of the engine's output. Each element in the list corresponds to a position in the game. The first entry in the list corresponds to the initial position of the game before any move has been made.

Note

The server analysis on lichess.org has a limit of 2250000 nodes. To mimic this, set limiter = 'nodes', and limit = 2250000.

See Also

The 'tabulate' functions tabulate analysis logs into data frames.

• tabulate_positionlog() for condensing analysis of one position.

• tabulate_gamelog() for condensing analysis of one game.

• tabulate_pgnlog() for condensing analysis of an entire pgn file.

The 'parse' functions extract specific data from analysis logs.

• parse_gamelog() for extracting data from one evaluated game.

• parse_pgnlog() for extracting data from games in a pgn.

The 'evaluate' functions produce analysis logs.

• evaluate_position() for analyzing chess positions.

• evaluate_game() for analyzing individual games.

• evaluate_pgn() for evaluating all the games in a PGN file.

Examples

movetext <- '1. e4 g5 2. Nc3 f5 3. Qh5# 1-0'
# Modify engine_path as required for your engine location & operating system
engine_path <- '//stockfish.exe'
evaluate_game(movetext, engine_path, n_pv = 1, limiter = 'depth', limit = 1)

dryguy/rbitr documentation built on Oct. 15, 2024, 6:18 a.m.