algorhino-anemone 0.1.1__py3-none-any.whl

anemone/nodes/algorithm_node/algorithm_node.py

@@ -0,0 +1,204 @@
+"""
+This module defines the AlgorithmNode class, which is a generic node used by the tree and value algorithm.
+It wraps tree nodes with values, minimax computation, and exploration tools.
+"""
+
+from typing import MutableMapping, Self
+
+from valanga import (
+    BranchKey,
+    BranchKeyGeneratorP,
+    ContentRepresentation,
+    State,
+    StateTag,
+)
+
+from anemone.indices.node_indices import NodeExplorationData
+from anemone.node_evaluation.node_tree_evaluation.node_tree_evaluation import (
+    NodeTreeEvaluation,
+)
+from anemone.nodes.tree_node import TreeNode
+
+
+class AlgorithmNode[StateT: State = State]:
+    """
+    The generic Node used by the tree and value algorithm.
+    It wraps tree nodes with values, minimax computation and exploration tools
+    """
+
+    tree_node: TreeNode[Self, StateT]
+    # the reference to the tree node that is wrapped pointing to other AlgorithmNodes
+    tree_evaluation: NodeTreeEvaluation[StateT]  # Use Any to break circular dependency
+    exploration_index_data: (
+        NodeExplorationData[Self, StateT] | None
+    )  # the object storing the information to help the algorithm decide the next nodes to explore
+    _state_representation: (
+        ContentRepresentation | None
+    )  # the state representation for evaluation
+
+    @property
+    def state_representation(self) -> ContentRepresentation | None:
+        """
+        Returns the state representation.
+        """
+        return self._state_representation
+
+    def __init__(
+        self,
+        tree_node: TreeNode[Self, StateT],
+        tree_evaluation: NodeTreeEvaluation[StateT],
+        exploration_index_data: NodeExplorationData[Self, StateT] | None,
+        state_representation: ContentRepresentation | None,
+    ) -> None:
+        """
+        Initializes an AlgorithmNode object.
+
+        Args:
+            tree_node (TreeNode): The tree node that is wrapped.
+            tree_evaluation (NodeTreeEvaluation): The object computing the value.
+            exploration_index_data (NodeExplorationData | None): The object storing the information to help the algorithm decide the next nodes to explore.
+            state_representation (StateRepresentation | None): The board representation.
+        """
+        self.tree_node = tree_node
+        self.tree_evaluation = tree_evaluation
+        self.exploration_index_data = exploration_index_data
+        self._state_representation = state_representation
+
+    @property
+    def id(self) -> int:
+        """
+        Returns the ID of the node.
+
+        Returns:
+            int: The ID of the node.
+        """
+        return self.tree_node.id
+
+    @property
+    def tree_depth(self) -> int:
+        """
+        Returns the tree depth.
+
+        Returns:
+            int: The tree depth.
+        """
+        return self.tree_node.tree_depth_
+
+    @property
+    def tag(self) -> StateTag:
+        """
+        Returns the fast representation of the node.
+
+        Returns:
+            str: The fast representation of the node.
+        """
+        return self.tree_node.tag
+
+    @property
+    def branches_children(self) -> MutableMapping[BranchKey, Self | None]:
+        """
+        Returns the bidirectional dictionary of moves and their corresponding child nodes.
+
+        Returns:
+            dict[IMove, ITreeNode | None]: The bidirectional dictionary of moves and their corresponding child nodes.
+        """
+        return self.tree_node.branches_children
+
+    @property
+    def parent_nodes(self) -> dict[Self, BranchKey]:
+        """
+        Returns the dictionary of parent nodes of the current tree node with associated move.
+
+        :return: A dictionary of parent nodes of the current tree node with associated move.
+        """
+        return self.tree_node.parent_nodes
+
+    @property
+    def state(self) -> StateT:
+        """
+        Returns the state associated with this tree node.
+
+        Returns:
+            StateWithTag: The state associated with this tree node.
+        """
+        return self.tree_node.state
+
+    def is_over(self) -> bool:
+        """
+        Checks if the game is over.
+
+        Returns:
+            bool: True if the game is over, False otherwise.
+        """
+        return self.tree_evaluation.is_over()
+
+    def add_parent(self, branch_key: BranchKey, new_parent_node: Self) -> None:
+        """
+        Adds a parent node.
+
+        Args:
+            branch_key (BranchKey): The branch key associated with the move that led to the node from the new_parent_node.
+            new_parent_node (ITreeNode): The new parent node to add.
+        """
+        self.tree_node.add_parent(
+            branch_key=branch_key, new_parent_node=new_parent_node
+        )
+
+    @property
+    def all_branches_keys(self) -> BranchKeyGeneratorP:
+        """
+        Returns a generator that yields the branch keys for the current board state.
+
+        Returns:
+            BranchKeyGenerator: A generator that yields the branch keys.
+        """
+        return self.tree_node.state_.branch_keys
+
+    @property
+    def all_branches_generated(self) -> bool:
+        """
+        Returns True if all branches have been generated, False otherwise.
+
+        Returns:
+            bool: True if all branches have been generated, False otherwise.
+        """
+        return self.tree_node.all_branches_generated
+
+    @all_branches_generated.setter
+    def all_branches_generated(self, value: bool) -> None:
+        """
+        Sets the flag indicating if all branches have been generated.
+
+        Args:
+            value (bool): The value to set.
+        """
+        self.tree_node.all_branches_generated = value
+
+    @property
+    def non_opened_branches(self) -> set[BranchKey]:
+        """
+        Returns the set of non-opened branches.
+
+        Returns:
+            set[BranchKey]: The set of non-opened branches.
+        """
+        return self.tree_node.non_opened_branches
+
+    def dot_description(self) -> str:
+        """
+        Returns the dot description of the node.
+
+        Returns:
+            str: The dot description of the node.
+        """
+        exploration_description: str = (
+            self.exploration_index_data.dot_description()
+            if self.exploration_index_data is not None
+            else ""
+        )
+
+        return f"{self.tree_node.dot_description()}\n{self.tree_evaluation.dot_description()}\n{exploration_description}"
+
+    def __str__(self) -> str:
+        """Return a concise string representation of the node."""
+        return f"{self.__class__} id :{self.tree_node.id}"

anemone/nodes/itree_node.py

@@ -0,0 +1,136 @@
+"""
+This module defines the interface for a tree node in a chess move selector.
+
+The `ITreeNode` protocol represents a node in a tree structure used for selecting chess moves.
+It provides properties and methods for accessing information about the node, such as its ID,
+the chess board state, the half move count, the child nodes, and the parent nodes.
+
+The `ITreeNode` protocol also defines methods for adding a parent node, generating a dot description
+for visualization, checking if all legal moves have been generated, accessing the legal moves,
+and checking if the game is over.
+
+Note: This is an interface and should not be instantiated directly.
+"""
+
+from typing import MutableMapping, Protocol, Self
+
+from valanga import BranchKey, BranchKeyGeneratorP, State, StateTag
+
+
+class ITreeNode[StateT: State = State](Protocol):
+    """
+    The `ITreeNode` protocol represents a node in a tree structure used for selecting chess moves.
+    """
+
+    @property
+    def id(self) -> int:
+        """
+        Get the ID of the node.
+
+        Returns:
+            The ID of the node.
+        """
+        ...
+
+    @property
+    def state(self) -> StateT:
+        """
+        Get the chess board state of the node.
+
+        Returns:
+            The chess board state of the node.
+        """
+        ...
+
+    @property
+    def tree_depth(self) -> int:
+        """
+        Get the tree depth of the node.
+
+        Returns:
+            The tree depth of the node.
+        """
+        ...
+
+    @property
+    def branches_children(self) -> MutableMapping[BranchKey, Self | None]:
+        """
+        Get the child nodes of the node.
+
+        Returns:
+            A bidirectional dictionary mapping branches to child nodes.
+        """
+        ...
+
+    @property
+    def parent_nodes(self) -> dict[Self, BranchKey]:
+        """
+        Returns the dictionary of parent nodes of the current tree node with associated move.
+
+        :return: A dictionary of parent nodes of the current tree node with associated move.
+        """
+        ...
+
+    def add_parent(self, branch_key: BranchKey, new_parent_node: Self) -> None:
+        """
+        Add a parent node to the node.
+
+        Args:
+            new_parent_node: The parent node to add.
+            move (chess.Move): the move that led to the node from the new_parent_node
+
+        """
+
+    def dot_description(self) -> str:
+        """
+        Generate a dot description for visualization.
+
+        Returns:
+            A string containing the dot description.
+        """
+        ...
+
+    @property
+    def all_branches_generated(self) -> bool:
+        """
+        Check if all branches have been generated.
+
+        Returns:
+            True if all branches have been generated, False otherwise.
+        """
+        ...
+
+    @all_branches_generated.setter
+    def all_branches_generated(self, value: bool) -> None:
+        """
+        Set the flag indicating that all branches have been generated.
+        """
+
+    @property
+    def all_branches_keys(self) -> BranchKeyGeneratorP:
+        """
+        Get the legal moves of the node.
+
+        Returns:
+            A generator for iterating over the legal moves.
+        """
+        ...
+
+    @property
+    def tag(self) -> StateTag:
+        """
+        Get the fast representation of the node.
+
+        Returns:
+            The fast representation of the node as a string.
+        """
+        ...
+
+    def is_over(self) -> bool:
+        """
+        Check if the game is over.
+
+        Returns:
+            True if the game is over, False otherwise.
+        """
+        ...

anemone/nodes/tree_node.py

@@ -0,0 +1,240 @@
+"""
+This module defines the TreeNode class, which represents a node in a tree structure for a chess game.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from valanga import BranchKey, BranchKeyGeneratorP, State, StateTag
+
+from .itree_node import ITreeNode
+
+# todo replace the any with a defaut value in ITReenode when availble in python; 3.13?
+
+
+@dataclass(slots=True)
+class TreeNode[
+    FamilyT: ITreeNode[Any] = ITreeNode[Any],
+    StateT: State = State,
+]:
+    r"""
+    The TreeNode class stores information about a specific board position, including the board representation,
+    the player to move, the half-move count, and the parent-child relationships with other nodes.
+
+    Attributes:
+        id\_ (int): The number to identify this node for easier debugging.
+        half_move\_ (int): The number of half-moves since the start of the game to reach the board position.
+        board\_ (boards.BoardChi): The board representation of the node.
+        parent_nodes\_ (set[ITreeNode]): The set of parent nodes to this node.
+        all_legal_moves_generated (bool): A boolean indicating whether all moves have been generated.
+        non_opened_legal_moves (set[chess.Move]): The set of non-opened legal moves.
+        moves_children\_ (dict[chess.Move, ITreeNode | None]): The dictionary mapping moves to child nodes.
+        fast_rep (str): The fast representation of the board.
+        player_to_move\_ (chess.Color): The color of the player that has to move in the board.
+
+    Methods:
+        __post_init__(): Initializes the TreeNode object after it has been created.
+        id(): Returns the id of the node.
+        player_to_move(): Returns the color of the player to move.
+        board(): Returns the board representation.
+        half_move(): Returns the number of half-moves.
+        moves_children(): Returns the dictionary mapping moves to child nodes.
+        parent_nodes(): Returns the set of parent nodes.
+        is_root_node(): Checks if the node is a root node.
+        legal_moves(): Returns the legal moves of the board.
+        add_parent(new_parent_node: ITreeNode): Adds a parent node to the current node.
+        is_over(): Checks if the game is over.
+        print_moves_children(): Prints the moves-children links of the node.
+        test(): Performs a test on the node.
+        dot_description(): Returns the dot description of the node.
+        test_all_legal_moves_generated(): Tests if all legal moves have been generated.
+        get_descendants(): Returns a dictionary of descendants of the node.
+    """
+
+    # id is a number to identify this node for easier debug
+    id_: int
+
+    # the tree depth of this node
+    tree_depth_: int
+
+    # the node holds a state.
+    state_: StateT
+
+    # the set of parent nodes to this node. Note that a node can have multiple parents!
+    parent_nodes_: dict[FamilyT, BranchKey]
+
+    # all_branches_generated is a boolean saying whether all branches have been generated.
+    # If true the branches are either opened in which case the corresponding opened node is stored in
+    # the dictionary self.branches_children, otherwise it is stored in self.non_opened_branches
+    all_branches_generated: bool = False
+
+    @staticmethod
+    def _empty_non_opened_branches() -> set[BranchKey]:
+        """Return a new empty set for non-opened branches."""
+        return set()
+
+    @staticmethod
+    def _empty_branches_children() -> dict[BranchKey, FamilyT | None]:
+        """Return a new empty mapping for branch children."""
+        return {}
+
+    non_opened_branches: set[BranchKey] = field(
+        default_factory=_empty_non_opened_branches
+    )
+
+    # dictionary mapping moves to children nodes. Node is set to None if not created
+    branches_children_: dict[BranchKey, FamilyT | None] = field(
+        default_factory=_empty_branches_children
+    )
+
+    @property
+    def tag(self) -> StateTag:
+        """Returns the fast representation of the board.
+
+        Returns:
+            boards.boardKey: The fast representation of the board.
+        """
+        return self.state_.tag
+
+    @property
+    def id(self) -> int:
+        """
+        Returns the ID of the tree node.
+
+        Returns:
+            int: The ID of the tree node.
+        """
+        return self.id_
+
+    @property
+    def state(self) -> StateT:
+        """
+        Returns the state associated with this tree node.
+
+        Returns:
+            State: The state associated with this tree node.
+        """
+        return self.state_
+
+    @property
+    def tree_depth(self) -> int:
+        """
+        Returns the tree depth of this node.
+
+        Returns:
+            int: The tree depth of this node.
+        """
+        return self.tree_depth_
+
+    @property
+    def branches_children(self) -> dict[BranchKey, FamilyT | None]:
+        """
+        Returns a bidirectional dictionary containing the children nodes of the current tree node,
+        along with the corresponding chess moves that lead to each child node.
+
+        Returns:
+            dict[BranchKey, ITreeNode | None]: A bidirectional dictionary mapping branches to
+            the corresponding child nodes. If a branch does not have a corresponding child node, it is
+            mapped to None.
+        """
+        return self.branches_children_
+
+    @property
+    def parent_nodes(self) -> dict[FamilyT, BranchKey]:
+        """
+        Returns the dictionary of parent nodes of the current tree node with associated move.
+
+        :return: A dictionary of parent nodes of the current tree node with associated move.
+        """
+        return self.parent_nodes_
+
+    def is_root_node(self) -> bool:
+        """
+        Check if the current node is a root node.
+
+        Returns:
+            bool: True if the node is a root node, False otherwise.
+        """
+        return not self.parent_nodes
+
+    @property
+    def all_branches_keys(self) -> BranchKeyGeneratorP:
+        """
+        Returns a generator that yields the branch keys for the current board state.
+
+        Returns:
+            BranchKeyGenerator: A generator that yields the branch keys.
+        """
+        return self.state_.branch_keys
+
+    def add_parent(self, branch_key: BranchKey, new_parent_node: FamilyT) -> None:
+        """
+        Adds a new parent node to the current node.
+
+        Args:
+            branch_key (BranchKey): The branch key associated with the move that led to the node from the new_parent_node.
+            new_parent_node (ITreeNode): The new parent node to be added.
+
+        Raises:
+            AssertionError: If the new parent node is already in the parent nodes set.
+
+        Returns:
+            None
+        """
+        # debug
+        assert (
+            new_parent_node not in self.parent_nodes
+        )  # there cannot be two ways to link the same child-parent
+        self.parent_nodes[new_parent_node] = branch_key
+
+    def is_over(self) -> bool:
+        """
+        Checks if the game is over.
+
+        Returns:
+            bool: True if the game is over, False otherwise.
+        """
+        return self.state.is_game_over()
+
+    def print_branches_children(self) -> None:
+        """
+        Prints the branches-children link of the node.
+
+        This method prints the branches-children link of the node, showing the branch and the ID of the child node.
+        If a child node is None, it will be displayed as 'None'.
+
+        Returns:
+            None
+        """
+        print(
+            "here are the ",
+            len(self.branches_children_),
+            " branches-children link of node",
+            self.id,
+            ": ",
+            end=" ",
+        )
+        for branch, child in self.branches_children_.items():
+            if child is None:
+                print(branch, child, end=" ")
+            else:
+                print(branch, child.id, end=" ")
+        print(" ")
+
+    def dot_description(self) -> str:
+        """
+        Returns a string representation of the node in the DOT format.
+
+        The string includes the node's ID, half move, and board FEN.
+
+        Returns:
+            A string representation of the node in the DOT format.
+        """
+        return (
+            "id:"
+            + str(self.id)
+            + " dep: "
+            + str(self.tree_depth)
+            + "\nfen:"
+            + str(self.state.tag)
+        )

anemone/nodes/tree_traversal.py

@@ -0,0 +1,108 @@
+"""
+This module provides functions for traversing a tree of nodes.
+
+The functions in this module allow you to retrieve descendants of a given node in a tree structure.
+"""
+
+from typing import Any
+
+from .algorithm_node import AlgorithmNode
+from .itree_node import ITreeNode
+
+
+def get_descendants[NodeT: ITreeNode[Any]](from_tree_node: NodeT) -> dict[NodeT, None]:
+    """
+    Get all descendants of a given tree node.
+
+    Args:
+        from_tree_node (ITreeNode): The starting tree node.
+
+    Returns:
+        dict[ITreeNode, None]: A dictionary containing all descendants of the starting tree node.
+    """
+    des: dict[NodeT, None] = {from_tree_node: None}  # include itself
+    generation: set[NodeT] = {
+        node for node in from_tree_node.branches_children.values() if node is not None
+    }
+
+    while generation:
+        next_depth_generation: set[NodeT] = set()
+        for node in generation:
+            assert node is not None
+            des[node] = None
+            for _, next_generation_child in node.branches_children.items():
+                if next_generation_child is not None:
+                    next_depth_generation.add(next_generation_child)
+        generation = next_depth_generation
+    return des
+
+
+def get_descendants_candidate_to_open[NodeT: AlgorithmNode[Any]](
+    from_tree_node: NodeT, max_depth: int | None = None
+) -> list[NodeT]:
+    """
+    Get descendants of a given tree node that are not over.
+
+    Args:
+        from_tree_node (AlgorithmNode): The starting tree node.
+        max_depth (int | None, optional): The maximum depth to traverse. Defaults to None.
+
+    Returns:
+        list[AlgorithmNode]: A list of descendants that are not over.
+    """
+    if not from_tree_node.all_branches_generated and not from_tree_node.is_over():
+        # should use are_all_moves_and_children_opened() but its messy!
+        # also using is_over is  messy as over_events are defined in a child class!!!
+        des = {from_tree_node: None}  # include itself maybe
+    else:
+        des = {}
+    generation: set[NodeT] = {
+        node for node in from_tree_node.branches_children.values() if node is not None
+    }
+    depth: int = 1
+    assert max_depth is not None
+    while generation and depth <= max_depth:
+        next_depth_generation: set[NodeT] = set()
+        for node in generation:
+            if not node.all_branches_generated and not node.is_over():
+                des[node] = None
+            for _, next_generation_child in node.branches_children.items():
+                if next_generation_child is not None:
+                    next_depth_generation.add(next_generation_child)
+        generation = next_depth_generation
+    return list(des.keys())
+
+
+def get_descendants_candidate_not_over[NodeT: AlgorithmNode[Any]](
+    from_tree_node: NodeT, max_depth: int | None = None
+) -> list[NodeT]:
+    """
+    Get descendants of a given tree node that are not over.
+
+    Args:
+        from_tree_node (ITreeNode): The starting tree node.
+        max_depth (int | None, optional): The maximum depth to traverse. Defaults to None.
+
+    Returns:
+        list[ITreeNode]: A list of descendants that are not over.
+    """
+    assert not from_tree_node.is_over()
+    if not from_tree_node.branches_children:
+        return [from_tree_node]
+    des: dict[NodeT, None] = {}
+    generation: set[NodeT] = {
+        node for node in from_tree_node.branches_children.values() if node is not None
+    }
+
+    depth: int = 1
+    assert max_depth is not None
+    while generation and depth <= max_depth:
+        next_depth_generation: set[NodeT] = set()
+        for node in generation:
+            if not node.is_over():
+                des[node] = None
+            for _, next_generation_child in node.branches_children.items():
+                if next_generation_child is not None:
+                    next_depth_generation.add(next_generation_child)
+        generation = next_depth_generation
+    return list(des.keys())