chipiron.players.move_selector.treevalue.trees package

Submodules

chipiron.players.move_selector.treevalue.trees.descendants module

This module defines the Descendants and RangedDescendants classes.

Descendants: - Represents a collection of descendants of a tree node at different half moves. - Provides methods to add, remove, and access descendants. - Keeps track of the number of descendants and the number of descendants at each half move.

RangedDescendants: - Inherits from Descendants and adds the ability to track a range of half moves. - Provides methods to check if a half move is within the current range or acceptable range. - Allows adding and removing descendants within the range. - Provides a method to get the range of half moves.

Note: The Descendants and RangedDescendants classes are used in the chipiron project for move selection in a game.

class chipiron.players.move_selector.treevalue.trees.descendants.Descendants[source]

Bases: object

Represents a collection of descendants for a specific half move in a tree.

Variables:

descendants_at_half_move (dict[HalfMove, dict[str, ITreeNode]]) – A dictionary that maps a half move to a dictionary of descendants.
number_of_descendants (int) – The total number of descendants in the collection.
number_of_descendants_at_half_move (dict[HalfMove, int]) – A dictionary that maps a half move to the number of descendants at that half move.
min_half_move (int | None) – The minimum half move in the collection, or None if the collection is empty.
max_half_move (int | None) – The maximum half move in the collection, or None if the collection is empty.

__getitem__(half_move: HalfMove) → dict[tuple[int, int, int, int, int, int, bool, int, int | None, int, int, int, int, int], chipiron.players.move_selector.treevalue.nodes.itree_node.ITreeNode[Any]][source]

Retrieve the descendants at a specific half move.

Parameters:: half_move (HalfMove) – The half move to retrieve the descendants for.
Returns:: A dictionary of descendants at the specified half move.
Return type:: dict[str, ITreeNode]

__iter__() → Iterator[HalfMove][source]

Returns an iterator over the descendants at each half move.

Returns:: An iterator over the descendants at each half move.

__len__() → int[source]

Returns the number of descendants at the current half move.

Returns:: The number of descendants at the current half move.
Return type:: int

__setitem__(half_move: HalfMove, value: dict[tuple[int, int, int, int, int, int, bool, int, int | None, int, int, int, int, int], chipiron.players.move_selector.treevalue.nodes.itree_node.ITreeNode[Any]]) → None[source]

Sets the descendants at a specific half move.

Parameters:

half_move (HalfMove) – The half move at which to set the descendants.
value (dict[str, ITreeNode]) – The descendants to set.

Returns:

None

add_descendant(node: ITreeNode[Any]) → None[source]

Adds a descendant node to the tree.

Parameters:: node (ITreeNode) – The descendant node to be added.
Returns:: None

contains_node(node: ITreeNode[Any]) → bool[source]

Checks if the descendants contain a specific node.

Parameters:: node (ITreeNode) – The node to check for.
Returns:: True if the descendants contain the node, False otherwise.
Return type:: bool

descendants_at_half_move: dict[HalfMove, dict[tuple[int, int, int, int, int, int, bool, int, int | None, int, int, int, int, int], chipiron.players.move_selector.treevalue.nodes.itree_node.ITreeNode[Any]]]

empty() → bool[source]

Check if the descendants are empty.

Returns:: True if the number of descendants is 0, False otherwise.
Return type:: bool

get_count() → int[source]

Returns the number of descendants for the current node.

Returns:: The number of descendants.
Return type:: int

iter_on_all_nodes() → Iterator[tuple[HalfMove, tuple[int, int, int, int, int, int, bool, int, int | None, int, int, int, int, int], chipiron.players.move_selector.treevalue.nodes.itree_node.ITreeNode[Any]]][source]

keys() → KeysView[HalfMove][source]

Returns a view of the keys in the descendants_at_half_move dictionary.

Returns:: A view of the keys in the descendants_at_half_move dictionary.
Return type:: KeysView[HalfMove]

max_half_move: int | None

min_half_move: int | None

number_of_descendants: int

number_of_descendants_at_half_move: dict[HalfMove, int]

print_info() → None[source]

Prints information about the descendants.

This method prints the number of descendants and their corresponding half moves. It also prints the ID and fast representation of each descendant.

Returns:: None

print_stats() → None[source]

Prints the statistics of the descendants.

This method prints the number of descendants at each half move.

Returns:: None

remove_descendant(node: ITreeNode[Any]) → None[source]

Removes a descendant node from the tree.

Parameters:: node (ITreeNode) – The node to be removed.
Returns:: None

test() → None[source]: This method performs a series of assertions to validate the descendants data structure. It checks if the number of descendants at each half move matches the number of descendants stored. It also checks if the sum of the lengths of all descendants at each half move matches the total number of descendants.

test_2(root_node: ITreeNode[Any]) → None[source]

Test the descendants of a given root node.

Parameters:: root_node (ITreeNode) – The root node to test.
Returns:: None

class chipiron.players.move_selector.treevalue.trees.descendants.RangedDescendants[source]

Bases: Descendants

Represents a collection of descendants with a range of half moves.

Variables:

min_half_move (int | None) – The minimum half move in the range.
max_half_move (int | None) – The maximum half move in the range.

__str__() → str[source]

Returns a string representation of the Descendants object.

The string includes information about each half move and its descendants.

Returns:: A string representation of the Descendants object.
Return type:: str

add_descendant(node: ITreeNode[Any]) → None[source]

Adds a descendant node to the tree.

Parameters:: node (ITreeNode) – The descendant node to be added.
Returns:: None

is_in_the_acceptable_range(half_move: int) → bool[source]

Checks if the given half_move is within the acceptable range.

Parameters:: half_move (int) – The half_move to check.
Returns:: True if the half_move is within the acceptable range, False otherwise.
Return type:: bool

is_in_the_current_range(half_move: int) → bool[source]

Checks if the given half_move is within the current range.

Parameters:: half_move (int) – The half_move to check.
Returns:: True if the half_move is within the range, False otherwise.
Return type:: bool

is_new_generation(half_move: HalfMove) → bool[source]

Checks if the given half move is a new generation.

Parameters:: half_move (HalfMove) – The half move to check.
Returns:: True if the half move is a new generation, False otherwise.
Return type:: bool

max_half_move: int | None

merge(descendant_1: Self, descendant_2: Self) → None[source]

Merges the descendants of two nodes into the current node.

Parameters:

descendant_1 (Self) – The first descendant node.
descendant_2 (Self) – The second descendant node.

Returns:

None

min_half_move: int | None

print_info() → None[source]

Prints information about the descendants.

This method calls the print_info method of the parent class and then prints the count of descendants, the minimum half move, and the maximum half move.

Returns:: None

range() → range[source]

Returns a range object representing the half moves range.

The range starts from the minimum half move and ends at the maximum half move.

Returns:: A range object representing the half moves range.
Return type:: range

remove_descendant(node: ITreeNode[Any]) → None[source]

Removes a descendant node from the tree.

Parameters:: node (ITreeNode) – The node to be removed.
Returns:: None

test() → None[source]

Perform a test on the descendants object.

This method checks the validity of the descendants object by asserting various conditions. If the min_half_move attribute is None, it asserts that max_half_move is also None and number_of_descendants is 0. Otherwise, it asserts that max_half_move and min_half_move are not None, and checks if all half moves between min_half_move and max_half_move are present in descendants_at_half_move dictionary. Finally, it iterates over all half moves in the descendants object and asserts that each half move is within the current range.

Returns:: None

class chipiron.players.move_selector.treevalue.trees.descendants.SortedDescendants[source]

Bases: Descendants

Represents a class that stores sorted descendants of a tree node at different half moves. Inherits from the Descendants class.

add_descendant_with_val(node: ITreeNode[Any], value: float) → None[source]

Adds a descendant node with its corresponding value.

Parameters:

node (ITreeNode) – The descendant node to add.
value (float) – The value of the descendant node.

contains_node(node: ITreeNode[Any]) → bool[source]

Checks if a descendant node is present in the data structure.

Parameters:: node (ITreeNode) – The descendant node to check.
Returns:: True if the descendant node is present, False otherwise.
Return type:: bool

print_info() → None[source]: Prints information about the sorted descendants.

remove_descendant(node: ITreeNode[Any]) → None[source]

Removes a descendant node from the data structure.

Parameters:: node (ITreeNode) – The descendant node to remove.

sorted_descendants_at_half_move: dict[int, dict[chipiron.players.move_selector.treevalue.nodes.itree_node.ITreeNode[Any], float]]

test() → None[source]: Performs a test to ensure the integrity of the data structure.

update_value(node: ITreeNode[Any], value: float) → None[source]

Updates the value of a descendant node.

Parameters:

node (ITreeNode) – The descendant node.
value (float) – The new value for the descendant node.

class chipiron.players.move_selector.treevalue.trees.descendants.SortedValueDescendants[source]

Bases: Descendants

Represents a class for managing sorted descendants with associated values. Inherits from the Descendants class.

add_descendant_val(node: ITreeNode[Any], value: float) → None[source]

Adds a descendant node with an associated value.

Parameters:

node (ITreeNode) – The descendant node to add.
value (float) – The value associated with the descendant node.

Returns:

None

print_info() → None[source]

Prints information about the sorted descendants.

Returns:: None

remove_descendant(node: ITreeNode[Any]) → None[source]

Removes a descendant node.

Parameters:: node (ITreeNode) – The descendant node to remove.
Returns:: None

sorted_descendants_at_half_move: dict[Any, Any]

test() → None[source]

Performs a test to ensure the integrity of the sorted descendants.

Returns:: None

update_value(node: ITreeNode[Any], value: float) → None[source]

Updates the value associated with a given node.

Parameters:

node (ITreeNode) – The node to update the value for.
value (float) – The new value to associate with the node.

Returns:

None

chipiron.players.move_selector.treevalue.trees.factory module

MoveAndValueTreeFactory

class chipiron.players.move_selector.treevalue.trees.factory.MoveAndValueTreeFactory(node_factory: AlgorithmNodeFactory, node_evaluator: NodeEvaluator)[source]

Bases: object

create(starting_board: IBoard) → MoveAndValueTree[source]

creates the tree

Parameters:: starting_board – the starting position

Returns:

node_evaluator: NodeEvaluator

node_factory: AlgorithmNodeFactory

chipiron.players.move_selector.treevalue.trees.move_and_value_tree module

MoveAndValueTree

class chipiron.players.move_selector.treevalue.trees.move_and_value_tree.MoveAndValueTree(root_node: AlgorithmNode, descendants: RangedDescendants)[source]

Bases: object

This class defines the Tree that is builds out of all the combinations of moves given a starting board position. The root node contains the starting board. Each node contains a board and has as many children node as there are legal move in the board. A children node then contains the board that is obtained by playing a particular moves in the board of the parent node.

It is pointer to the root node with some counters and keeping track of descendants.

descendants: RangedDescendants

evaluate() → FloatyBoardEvaluation | ForcedOutcome[source]

is_over() → bool[source]

Check if the game is over.

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

node_depth(node: ITreeNode[Any]) → int[source]

Calculates the depth of a given node in the tree.

Parameters:: node (nodes.ITreeNode) – The node for which to calculate the depth.
Returns:: The depth of the node.
Return type:: int

property root_node: AlgorithmNode

Returns the root node of the move and value tree.

Returns:: The root node of the move and value tree.
Return type:: AlgorithmNode

tree_root_half_move: int

chipiron.players.move_selector.treevalue.trees.tree_visualization module

This module provides functions for visualizing and saving tree structures.

The functions in this module allow for the visualization of tree structures using the Graphviz library. It provides a way to display the tree structure as a graph and save it as a PDF file. Additionally, it provides a function to save the raw data of the tree structure to a file using pickle.

Functions: - add_dot(dot: Digraph, treenode: ITreeNode) -> None: Adds nodes and edges to the graph representation of the tree. - display_special(node: ITreeNode, format: str, index: dict[chess.Move, str]) -> Digraph: Displays a special representation of the tree with additional information. - display(tree: MoveAndValueTree, format_str: str) -> Digraph: Displays the tree structure as a graph. - save_pdf_to_file(tree: MoveAndValueTree) -> None: Saves the tree structure as a PDF file. - save_raw_data_to_file(tree: MoveAndValueTree, count: str = ‘#’) -> None: Saves the raw data of the tree structure to a file.

chipiron.players.move_selector.treevalue.trees.tree_visualization.add_dot(dot: Digraph, treenode: ITreeNode[Any]) → None[source]

Adds a node and edges to the given Dot graph based on the provided tree node.

Parameters:

dot (Digraph) – The Dot graph to add the node and edges to.
treenode (ITreeNode) – The tree node to visualize.

Returns:

None

chipiron.players.move_selector.treevalue.trees.tree_visualization.display(tree: MoveAndValueTree, format_str: str) → Digraph[source]

Display the move and value tree using graph visualization.

Parameters:

tree (MoveAndValueTree) – The move and value tree to be displayed.
format_str (str) – The format of the output graph (e.g., ‘png’, ‘pdf’, ‘svg’).

Returns:

The graph representation of the move and value tree.

Return type:

Digraph

chipiron.players.move_selector.treevalue.trees.tree_visualization.display_special(node: ITreeNode[Any], format_str: str, index: dict[int, str]) → Digraph[source]

Display a special visualization of a tree node and its children.

Parameters:

node (ITreeNode) – The tree node to display.
format_str (str) – The format of the output graph (e.g., ‘png’, ‘pdf’, ‘svg’).
index (Dict[chess.Move, str]) – A dictionary mapping chess moves to their descriptions.

Returns:

The graph representing the tree visualization.

Return type:

Digraph

Raises:

AssertionError – If the child node is None or if the parent node is not an AlgorithmNode.

chipiron.players.move_selector.treevalue.trees.tree_visualization.save_pdf_to_file(tree: MoveAndValueTree) → None[source]

Saves the visualization of a tree as a PDF file.

Parameters:: tree (MoveAndValueTree) – The tree to be visualized and saved.
Returns:: None

chipiron.players.move_selector.treevalue.trees.tree_visualization.save_raw_data_to_file(tree: MoveAndValueTree, count: str = '#') → None[source]

Save raw data of a MoveAndValueTree to a file.

Parameters:

tree (MoveAndValueTree) – The MoveAndValueTree object to save.
count (str, optional) – A string to append to the filename. Defaults to ‘#’.

Returns:

None

Module contents

init file for trees module

class chipiron.players.move_selector.treevalue.trees.Descendants[source]

Bases: object

Represents a collection of descendants for a specific half move in a tree.

Variables:

descendants_at_half_move (dict[HalfMove, dict[str, ITreeNode]]) – A dictionary that maps a half move to a dictionary of descendants.
number_of_descendants (int) – The total number of descendants in the collection.
number_of_descendants_at_half_move (dict[HalfMove, int]) – A dictionary that maps a half move to the number of descendants at that half move.
min_half_move (int | None) – The minimum half move in the collection, or None if the collection is empty.
max_half_move (int | None) – The maximum half move in the collection, or None if the collection is empty.

__getitem__(half_move: HalfMove) → dict[tuple[int, int, int, int, int, int, bool, int, int | None, int, int, int, int, int], chipiron.players.move_selector.treevalue.nodes.itree_node.ITreeNode[Any]][source]

Retrieve the descendants at a specific half move.

Parameters:: half_move (HalfMove) – The half move to retrieve the descendants for.
Returns:: A dictionary of descendants at the specified half move.
Return type:: dict[str, ITreeNode]

__iter__() → Iterator[HalfMove][source]

Returns an iterator over the descendants at each half move.

Returns:: An iterator over the descendants at each half move.

__len__() → int[source]

Returns the number of descendants at the current half move.

Returns:: The number of descendants at the current half move.
Return type:: int

__setitem__(half_move: HalfMove, value: dict[tuple[int, int, int, int, int, int, bool, int, int | None, int, int, int, int, int], chipiron.players.move_selector.treevalue.nodes.itree_node.ITreeNode[Any]]) → None[source]

Sets the descendants at a specific half move.

Parameters:

half_move (HalfMove) – The half move at which to set the descendants.
value (dict[str, ITreeNode]) – The descendants to set.

Returns:

None

add_descendant(node: ITreeNode[Any]) → None[source]

Adds a descendant node to the tree.

Parameters:: node (ITreeNode) – The descendant node to be added.
Returns:: None

contains_node(node: ITreeNode[Any]) → bool[source]

Checks if the descendants contain a specific node.

Parameters:: node (ITreeNode) – The node to check for.
Returns:: True if the descendants contain the node, False otherwise.
Return type:: bool

descendants_at_half_move: dict[HalfMove, dict[tuple[int, int, int, int, int, int, bool, int, int | None, int, int, int, int, int], chipiron.players.move_selector.treevalue.nodes.itree_node.ITreeNode[Any]]]

empty() → bool[source]

Check if the descendants are empty.

Returns:: True if the number of descendants is 0, False otherwise.
Return type:: bool

get_count() → int[source]

Returns the number of descendants for the current node.

Returns:: The number of descendants.
Return type:: int

iter_on_all_nodes() → Iterator[tuple[HalfMove, tuple[int, int, int, int, int, int, bool, int, int | None, int, int, int, int, int], chipiron.players.move_selector.treevalue.nodes.itree_node.ITreeNode[Any]]][source]

keys() → KeysView[HalfMove][source]

Returns a view of the keys in the descendants_at_half_move dictionary.

Returns:: A view of the keys in the descendants_at_half_move dictionary.
Return type:: KeysView[HalfMove]

max_half_move: int | None

min_half_move: int | None

number_of_descendants: int

number_of_descendants_at_half_move: dict[HalfMove, int]

print_info() → None[source]

Prints information about the descendants.

This method prints the number of descendants and their corresponding half moves. It also prints the ID and fast representation of each descendant.

Returns:: None

print_stats() → None[source]

Prints the statistics of the descendants.

This method prints the number of descendants at each half move.

Returns:: None

remove_descendant(node: ITreeNode[Any]) → None[source]

Removes a descendant node from the tree.

Parameters:: node (ITreeNode) – The node to be removed.
Returns:: None

test() → None[source]: This method performs a series of assertions to validate the descendants data structure. It checks if the number of descendants at each half move matches the number of descendants stored. It also checks if the sum of the lengths of all descendants at each half move matches the total number of descendants.

test_2(root_node: ITreeNode[Any]) → None[source]

Test the descendants of a given root node.

Parameters:: root_node (ITreeNode) – The root node to test.
Returns:: None

class chipiron.players.move_selector.treevalue.trees.MoveAndValueTree(root_node: AlgorithmNode, descendants: RangedDescendants)[source]

Bases: object

This class defines the Tree that is builds out of all the combinations of moves given a starting board position. The root node contains the starting board. Each node contains a board and has as many children node as there are legal move in the board. A children node then contains the board that is obtained by playing a particular moves in the board of the parent node.

It is pointer to the root node with some counters and keeping track of descendants.

descendants: RangedDescendants

evaluate() → FloatyBoardEvaluation | ForcedOutcome[source]

is_over() → bool[source]

Check if the game is over.

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

node_depth(node: ITreeNode[Any]) → int[source]

Calculates the depth of a given node in the tree.

Parameters:: node (nodes.ITreeNode) – The node for which to calculate the depth.
Returns:: The depth of the node.
Return type:: int

property root_node: AlgorithmNode

Returns the root node of the move and value tree.

Returns:: The root node of the move and value tree.
Return type:: AlgorithmNode

tree_root_half_move: int

class chipiron.players.move_selector.treevalue.trees.RangedDescendants[source]

Bases: Descendants

Represents a collection of descendants with a range of half moves.

Variables:

min_half_move (int | None) – The minimum half move in the range.
max_half_move (int | None) – The maximum half move in the range.

__str__() → str[source]

Returns a string representation of the Descendants object.

The string includes information about each half move and its descendants.

Returns:: A string representation of the Descendants object.
Return type:: str

add_descendant(node: ITreeNode[Any]) → None[source]

Adds a descendant node to the tree.

Parameters:: node (ITreeNode) – The descendant node to be added.
Returns:: None

descendants_at_half_move: dict[HalfMove, dict[tuple[int, int, int, int, int, int, bool, int, int | None, int, int, int, int, int], chipiron.players.move_selector.treevalue.nodes.itree_node.ITreeNode[Any]]]

is_in_the_acceptable_range(half_move: int) → bool[source]

Checks if the given half_move is within the acceptable range.

Parameters:: half_move (int) – The half_move to check.
Returns:: True if the half_move is within the acceptable range, False otherwise.
Return type:: bool

is_in_the_current_range(half_move: int) → bool[source]

Checks if the given half_move is within the current range.

Parameters:: half_move (int) – The half_move to check.
Returns:: True if the half_move is within the range, False otherwise.
Return type:: bool

is_new_generation(half_move: HalfMove) → bool[source]

Checks if the given half move is a new generation.

Parameters:: half_move (HalfMove) – The half move to check.
Returns:: True if the half move is a new generation, False otherwise.
Return type:: bool

max_half_move: int | None

merge(descendant_1: Self, descendant_2: Self) → None[source]

Merges the descendants of two nodes into the current node.

Parameters:

descendant_1 (Self) – The first descendant node.
descendant_2 (Self) – The second descendant node.

Returns:

None

min_half_move: int | None

number_of_descendants: int

number_of_descendants_at_half_move: dict[HalfMove, int]

print_info() → None[source]

Prints information about the descendants.

This method calls the print_info method of the parent class and then prints the count of descendants, the minimum half move, and the maximum half move.

Returns:: None

range() → range[source]

Returns a range object representing the half moves range.

The range starts from the minimum half move and ends at the maximum half move.

Returns:: A range object representing the half moves range.
Return type:: range

remove_descendant(node: ITreeNode[Any]) → None[source]

Removes a descendant node from the tree.

Parameters:: node (ITreeNode) – The node to be removed.
Returns:: None

test() → None[source]

Perform a test on the descendants object.

This method checks the validity of the descendants object by asserting various conditions. If the min_half_move attribute is None, it asserts that max_half_move is also None and number_of_descendants is 0. Otherwise, it asserts that max_half_move and min_half_move are not None, and checks if all half moves between min_half_move and max_half_move are present in descendants_at_half_move dictionary. Finally, it iterates over all half moves in the descendants object and asserts that each half move is within the current range.

Returns:: None

chipiron.players.move_selector.treevalue.trees.save_raw_data_to_file(tree: MoveAndValueTree, count: str = '#') → None[source]

Save raw data of a MoveAndValueTree to a file.

Parameters:

tree (MoveAndValueTree) – The MoveAndValueTree object to save.
count (str, optional) – A string to append to the filename. Defaults to ‘#’.

Returns:

None