chipiron.players.boardevaluators package

Subpackages

Submodules

chipiron.players.boardevaluators.basic_evaluation module

Module for the basic evaluation of a chess board.

class chipiron.players.boardevaluators.basic_evaluation.BasicEvaluation(*args, **kwargs)[source]

Bases: BoardEvaluator

A basic board evaluator that calculates the value of the board for the white player.

Parameters:: BoardEvaluator (type) – The base class for board evaluators.
Variables:: None –

value_white()[source]: Calculates the value of the board for the white player.

value_white(board: IBoard) → float[source]

Calculates the value of the board for the white player.

Parameters:: board (BoardChi) – The chess board.
Returns:: The value of the board for the white player.
Return type:: float

chipiron.players.boardevaluators.basic_evaluation.add_pawns_value_black(board: IBoard) → float[source]

Calculate the value to be added for black pawns based on their position.

This function calculates the value to be added for black pawns based on their position on the board. The value is determined by giving more value to the pawns that are advanced.

Parameters:: board (BoardChi) – The chess board.
Returns:: The value to be added for black pawns.
Return type:: float

chipiron.players.boardevaluators.basic_evaluation.add_pawns_value_white(board: IBoard) → float[source]

Calculate the additional value for white pawns based on their advancement.

Parameters:: board (BoardChi) – The chess board.
Returns:: The additional value for white pawns.
Return type:: float

chipiron.players.boardevaluators.basic_evaluation.sigmoid(x: float) → float[source]

Calculate the sigmoid function of a given input.

Parameters:: x (float) – The input value.
Returns:: The result of the sigmoid function.
Return type:: float

chipiron.players.boardevaluators.basic_evaluation.value_base(board: IBoard, color: bool) → int[source]

Calculate the base value of the given board for the specified color.

Parameters:

board (BoardChi) – The chess board.
color (chess.Color) – The color for which to calculate the value.

Returns:

The base value of the board for the specified color.

Return type:

int

chipiron.players.boardevaluators.basic_evaluation.value_player_to_move(board: IBoard) → float[source]

Calculate the value of the player to move.

This function calculates the value of the player to move based on the difference in piece values between the two players on the board.

Parameters:: board (BoardChi) – The chess board.
Returns:: The value of the player to move.
Return type:: float

chipiron.players.boardevaluators.basic_evaluation.value_white(board: IBoard) → float[source]

Calculate the value of the white pieces on the board.

This function calculates the value of the white pieces on the board by subtracting the value of the black pieces from the value of the white pieces.

Parameters:: board (BoardChi) – The chess board.
Returns:: The value of the white pieces on the board.
Return type:: float

chipiron.players.boardevaluators.board_evaluator module

Module representing the board evaluators.

class chipiron.players.boardevaluators.board_evaluator.BoardEvaluator(*args, **kwargs)[source]

Bases: Protocol

Protocol representing a board evaluator.

value_white(board: IBoard) → float[source]: Evaluates a board and returns the value for white.

class chipiron.players.boardevaluators.board_evaluator.GameBoardEvaluator(board_evaluator_stock: BoardEvaluator | None, board_evaluator_chi: BoardEvaluator)[source]

Bases: object

This class is a collection of evaluators that display their analysis during the game. They are not players, just external analysis and display.

add_evaluation(player_color: bool, evaluation: FloatyBoardEvaluation | ForcedOutcome) → None[source]: Adds an evaluation value for a player.

board_evaluator_chi: BoardEvaluator

board_evaluator_stock: BoardEvaluator | None

evaluate(board: IBoard) → tuple[float | None, float][source]: Evaluates a board and returns the evaluation values for stock and chi.

class chipiron.players.boardevaluators.board_evaluator.IGameBoardEvaluator(*args, **kwargs)[source]

Bases: Protocol

Protocol representing a game board evaluator.

add_evaluation(player_color: bool, evaluation: FloatyBoardEvaluation | ForcedOutcome) → None[source]: Adds an evaluation value for a player.

evaluate(board: IBoard) → tuple[float | None, float][source]: Evaluates a board and returns the evaluation values for stock and chi.

class chipiron.players.boardevaluators.board_evaluator.ObservableBoardEvaluator(game_board_evaluator: GameBoardEvaluator)[source]

Bases: object

This class represents an observable board evaluator.

add_evaluation(player_color: bool, evaluation: FloatyBoardEvaluation | ForcedOutcome) → None[source]: Adds an evaluation value for a player.

evaluate(board: IBoard) → tuple[float | None, float][source]: Evaluates a board and returns the evaluation values for stock and chi.

evaluation_chi: Any

evaluation_player_black: Any

evaluation_player_white: Any

evaluation_stock: Any

game_board_evaluator: GameBoardEvaluator

mailboxes: list[queue.Queue[chipiron.utils.dataclass.IsDataclass]]

notify_new_results() → None[source]: Notifies the subscribers about the new evaluation results.

subscribe(mailbox: Queue[IsDataclass]) → None[source]

Subscribe to the ObservableBoardEvaluator to get the EvaluationMessage.

Parameters:: mailbox – The mailbox queue.

chipiron.players.boardevaluators.factory module

Module for creating board evaluators.

class chipiron.players.boardevaluators.factory.BasicEvaluationArgs[source]

Bases: object

A class representing the arguments for basic evaluation.

This class provides a way to store and access the arguments needed for basic evaluation.

Variables:: None –

``None``

class chipiron.players.boardevaluators.factory.BoardEvalArgsWrapper(board_evaluator: NeuralNetBoardEvalArgs | StockfishBoardEvalArgs | TableBaseArgs | BasicEvaluationArgs)[source]

Bases: object

A wrapper class for the BoardEvalArgs object.

This class provides a convenient way to access the board_evaluator attribute of the BoardEvalArgs object.

Variables:: board_evaluator (BoardEvalArgs) – The BoardEvalArgs object to be wrapped.

board_evaluator: NeuralNetBoardEvalArgs | StockfishBoardEvalArgs | TableBaseArgs | BasicEvaluationArgs

class chipiron.players.boardevaluators.factory.TableBaseArgs[source]

Bases: object

A class representing the arguments for the TableBase class.

This class provides a template for the arguments that can be passed to the TableBase class. It serves as a base class for defining specific argument classes for different implementations of the TableBase class.

Variables:: None –

``None``

chipiron.players.boardevaluators.factory.create_board_evaluator(args_board_evaluator: NeuralNetBoardEvalArgs | StockfishBoardEvalArgs | TableBaseArgs | BasicEvaluationArgs) → BoardEvaluator[source]

Create a board evaluator based on the given arguments.

Parameters:: args_board_evaluator (BoardEvalArgs) – The arguments for the board evaluator.
Returns:: The created board evaluator.
Return type:: BoardEvaluator
Raises:: SystemExit – If the given arguments do not match any supported board evaluator.

chipiron.players.boardevaluators.factory.create_game_board_evaluator(gui: bool, can_stockfish: bool) → IGameBoardEvaluator[source]

Create a game board evaluator based on the given GUI flag.

Parameters:: gui (bool) – A flag indicating whether the GUI is enabled or not.
Returns:: An instance of the game board evaluator.
Return type:: IGameBoardEvaluator

chipiron.players.boardevaluators.factory.create_game_board_evaluator_not_observable(can_stockfish: bool) → GameBoardEvaluator[source]

Create a game board evaluator that is not observable.

This function creates a game board evaluator that consists of two board evaluators: - board_evaluator_stock: A board evaluator created using the StockfishBoardEvalArgs. - board_evaluator_chi: A board evaluator created using the board evaluator configuration specified in the ‘base_chipiron_board_eval.yaml’ file.

Returns:: The created game board evaluator.
Return type:: GameBoardEvaluator

chipiron.players.boardevaluators.over_event module

Module for handling game over events.

class chipiron.players.boardevaluators.over_event.HowOver(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Represents the possible outcomes of a game.

Variables:

WIN (int) – Indicates a win.
DRAW (int) – Indicates a draw.
DO_NOT_KNOW_OVER (int) – Indicates that the outcome is unknown.

DO_NOT_KNOW_OVER = 3

DRAW = 2

WIN = 1

class chipiron.players.boardevaluators.over_event.OverEvent(how_over: HowOver = HowOver.DO_NOT_KNOW_OVER, who_is_winner: Winner = Winner.NO_KNOWN_WINNER, termination: Termination | None = None)[source]

Bases: object

Represents an event that indicates the end of a game.

Variables:

how_over (HowOver) – The way the game ended.
who_is_winner (Winner) – The winner of the game.

Raises:

AssertionError – If the how_over attribute is not a valid value from the HowOver enum.
AssertionError – If the who_is_winner attribute is not a valid value from the Winner enum.
Exception – If the winner is not properly defined.

__post_init__()[source]: Performs additional initialization after the object is created.

becomes_over()[source]: Sets the how_over and who_is_winner attributes.

get_over_tag()[source]: Returns a tag string used in databases.

__bool__()[source]: Raises an exception.

is_over()[source]: Checks if the game is over.

is_win()[source]: Checks if the game ended with a win.

is_draw()[source]: Checks if the game ended with a draw.

is_winner()[source]: Checks if the specified player is the winner.

print_info()[source]: Prints information about the OverEvent object.

test()[source]: Performs tests on the OverEvent object.

__bool__() → None[source]

Raises an exception.

Raises:: Exception – Always raises an exception.

becomes_over(how_over: HowOver, termination: Termination | None, who_is_winner: Winner = Winner.NO_KNOWN_WINNER) → None[source]

Sets the how_over and who_is_winner attributes.

Parameters:

how_over (HowOver) – The way the game ended.
who_is_winner (Winner, optional) – The winner of the game. Defaults to Winner.NO_KNOWN_WINNER.

get_over_tag() → OverTags[source]

Returns a tag string used in databases.

Returns:: The tag string representing the game outcome.
Return type:: OverTags
Raises:: Exception – If the winner is not properly defined.

how_over: HowOver

is_draw() → bool[source]

Checks if the game ended with a draw.

Returns:: True if the game ended with a draw, False otherwise.
Return type:: bool

is_over() → bool[source]

Checks if the game is over.

Returns:: True if the game is over, False otherwise.
Return type:: bool

is_win() → bool[source]

Checks if the game ended with a win.

Returns:: True if the game ended with a win, False otherwise.
Return type:: bool

is_winner(player: bool) → bool[source]

Checks if the specified player is the winner.

Parameters:: player (chess.Color) – The player to check.
Returns:: True if the specified player is the winner, False otherwise.
Return type:: bool
Raises:: AssertionError – If the player argument is not a valid value from the chess.Color enum.

print_info() → None[source]: Prints information about the OverEvent object.

termination: Termination | None

test() → None[source]: Performs tests on the OverEvent object.

who_is_winner: Winner

class chipiron.players.boardevaluators.over_event.OverTags(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Represents the possible tags for game over events.

Variables:

TAG_WIN_WHITE (str) – Tag indicating a win for the white player.
TAG_WIN_BLACK (str) – Tag indicating a win for the black player.
TAG_DRAW (str) – Tag indicating a draw.
TAG_DO_NOT_KNOW (str) – Tag indicating an unknown outcome.

TAG_DO_NOT_KNOW = '?'

TAG_DRAW = 'Draw'

TAG_WIN_BLACK = 'Win-Bl'

TAG_WIN_WHITE = 'Win-Wh'

class chipiron.players.boardevaluators.over_event.Winner(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Represents the winner of a chess game.

Parameters:

Enum – The base class for enumeration types.

Variables:

WHITE (Winner) – Represents the winner as white.
BLACK (Winner) – Represents the winner as black.
NO_KNOWN_WINNER (Winner) – Represents the absence of a known winner.

is_none() → bool[source]: Checks if the winner is None.

is_white() → bool[source]: Checks if the winner is white.

is_black() → bool[source]: Checks if the winner is black.

BLACK = False

NO_KNOWN_WINNER = None

WHITE = True

is_black() → bool[source]

Check if the winner is black.

Returns:: True if the winner is black, False otherwise.
Return type:: bool

is_none() → bool[source]

Check if the winner is None.

Returns:: True if the winner is None, False otherwise.
Return type:: bool

is_white() → bool[source]

Check if the winner is white.

Returns:: True if the winner is white, False otherwise.
Return type:: bool

chipiron.players.boardevaluators.stockfish_board_evaluator module

Module where we define the Stockfish Board Evaluator

class chipiron.players.boardevaluators.stockfish_board_evaluator.StockfishBoardEvalArgs(depth: int = 20, time_limit: float = 0.1)[source]

Bases: object

Represents the arguments for the Stockfish board evaluator.

Variables:

depth (int) – The depth of the search algorithm.
time_limit (float) – The time limit for the search algorithm.

depth: int = 20

time_limit: float = 0.1

class chipiron.players.boardevaluators.stockfish_board_evaluator.StockfishBoardEvaluator(args: StockfishBoardEvalArgs)[source]

Bases: object

A board evaluator powered by stockfish

engine: SimpleEngine | None

value_white(board: IBoard) → float[source]

Computes the value of the board for the white player.

Parameters:: board (boards.BoardChi) – The board object representing the current state of the game.
Returns:: The value of the board for the white player.
Return type:: float

chipiron.players.boardevaluators.test_over_event module

Module for testing the OverEvent class.

class chipiron.players.boardevaluators.test_over_event.TestOverEvent(methodName='runTest')[source]

Bases: TestCase

A test case for the OverEvent class.

test_construct_over_events() → None[source]: Test the construction of OverEvent instances.

Module contents

This module provides board evaluators for the chipiron game.

The board evaluators are used to evaluate the current state of the game board and assign a value to it.

class chipiron.players.boardevaluators.BoardEvaluator(*args, **kwargs)[source]

Bases: Protocol

Protocol representing a board evaluator.

value_white(board: IBoard) → float[source]: Evaluates a board and returns the value for white.

class chipiron.players.boardevaluators.MasterBoardEvaluator(board_evaluator: BoardEvaluator, syzygy: SyzygyTable[Any] | None, value_over_enum: Type[ValueWhiteWhenOverSymmetricUnitInterval] | Type[ValueWhiteWhenOverEntireRealAxis])[source]

Bases: object

The MasterBoardEvaluator class is responsible for evaluating the value of nodes in a tree structure. It uses a board evaluator and a syzygy evaluator to calculate the value of the nodes.

board_evaluator: BoardEvaluator

check_obvious_over_events(board: IBoard) → tuple[chipiron.players.boardevaluators.over_event.OverEvent | None, float | None][source]

Checks if the given board is in an obvious game-over state and returns the corresponding OverEvent and evaluation.

Parameters:: board (boards.IBoard) – The board to evaluate for game-over conditions.
Raises:: ValueError – If the board result string is not recognized.
Returns:: A tuple containing the OverEvent (if the game is over or can be determined from Syzygy tables, otherwise None) and the evaluation score from White’s perspective. The evaluation is especially useful when training models.
Return type:: tuple[OverEvent | None, float]

syzygy_evaluator: SyzygyTable[Any] | None

syzygy_value_white(board: IBoard) → float | None[source]: Calculates the value for the white player of a given board using the syzygy evaluator. If the syzygy evaluator is not available or the board is not in the syzygy table, None is returned.

value_over_enum: Type[ValueWhiteWhenOverSymmetricUnitInterval] | Type[ValueWhiteWhenOverEntireRealAxis]

value_white(board: IBoard) → float[source]: Calculates the value for the white player of a given node. If the value can be obtained from the syzygy evaluator, it is used. Otherwise, the board evaluator is used.

value_white_from_over_event(over_event: OverEvent) → float[source]: Returns the value white given an over event.