algorhino-anemone 0.1.1__py3-none-any.whl

anemone/trees/factory.py

@@ -0,0 +1,80 @@
+"""
+ValueTreeFactory
+"""
+
+from valanga import State
+
+from anemone import node_factory as nod_fac
+from anemone.node_evaluation.node_direct_evaluation.node_direct_evaluator import (
+    EvaluationQueries,
+    NodeDirectEvaluator,
+)
+from anemone.nodes.algorithm_node.algorithm_node import AlgorithmNode
+from anemone.trees.tree import Tree
+
+from .descendants import RangedDescendants
+
+
+class ValueTreeFactory[StateT: State = State]:
+    """
+    ValueTreeFactory
+    """
+
+    node_factory: nod_fac.AlgorithmNodeFactory[StateT]
+    node_direct_evaluator: NodeDirectEvaluator[StateT]
+
+    def __init__(
+        self,
+        node_factory: nod_fac.AlgorithmNodeFactory[StateT],
+        node_direct_evaluator: NodeDirectEvaluator[StateT],
+    ) -> None:
+        """
+        creates the tree factory
+        Args:
+            node_factory:
+            node_evaluator:
+        """
+        self.node_factory = node_factory
+        self.node_direct_evaluator = node_direct_evaluator
+
+    def create(self, starting_state: StateT) -> Tree[AlgorithmNode[StateT]]:
+        """
+        creates the tree
+
+        Args:
+            starting_state: the starting position
+
+        Returns:
+
+        """
+
+        root_node: AlgorithmNode[StateT] = self.node_factory.create(
+            state=starting_state,
+            tree_depth=0,  # by default
+            count=0,
+            parent_node=None,
+            modifications=None,
+            branch_from_parent=None,
+        )
+
+        evaluation_queries: EvaluationQueries[StateT] = EvaluationQueries()
+
+        self.node_direct_evaluator.add_evaluation_query(
+            node=root_node, evaluation_queries=evaluation_queries
+        )
+
+        self.node_direct_evaluator.evaluate_all_queried_nodes(
+            evaluation_queries=evaluation_queries
+        )
+        # is this needed? used outside?
+
+        descendants: RangedDescendants[AlgorithmNode[StateT]] = RangedDescendants[
+            AlgorithmNode[StateT]
+        ]()
+        descendants.add_descendant(root_node)
+
+        value_tree: Tree[AlgorithmNode[StateT]] = Tree[AlgorithmNode[StateT]](
+            root_node=root_node, descendants=descendants
+        )
+
+        return value_tree

anemone/trees/tree.py

@@ -0,0 +1,70 @@
+"""
+Tree
+"""
+
+from typing import Any
+
+from anemone.basics import TreeDepth
+from anemone.nodes.itree_node import ITreeNode
+
+from .descendants import RangedDescendants
+
+
+class Tree[NodeT: ITreeNode[Any]]:
+    """
+    This class defines the Tree that is built 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 a pointer to the root node with some counters and keeping track of descendants.
+    """
+
+    _root_node: NodeT
+    descendants: RangedDescendants[NodeT]
+    tree_root_tree_depth: TreeDepth
+
+    def __init__(self, root_node: NodeT, descendants: RangedDescendants[NodeT]) -> None:
+        """
+        Initialize the Tree with a root node and descendants.
+
+        Args:
+            root_node: The root node of the tree.
+            descendants: The descendants collection for the tree.
+        """
+        self.tree_root_tree_depth = root_node.tree_depth
+
+        # number of nodes in the tree (already one as we have the root node provided)
+        self.nodes_count = 1
+
+        # integer counting the number of moves in the tree.
+        # the interest of self.move_count over the number of nodes in the descendants
+        # is that is always increasing at each opening,
+        # while self.node_count can stay the same if the nodes already existed.
+        self.move_count = 0
+
+        self._root_node = root_node
+        self.descendants = descendants
+
+    @property
+    def root_node(self) -> NodeT:
+        """
+        Returns the root node of the tree.
+
+        Returns:
+            NodeT: The root node of the tree.
+        """
+        return self._root_node
+
+    def node_depth(self, node: NodeT) -> int:
+        """
+        Calculates the depth of a given node in the tree.
+
+        Args:
+            node: The node for which to calculate the depth.
+
+        Returns:
+            int: The depth of the node.
+        """
+        return node.tree_depth - self.tree_root_tree_depth

anemone/trees/tree_visualization.py

@@ -0,0 +1,143 @@
+"""
+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: ValueTree, format_str: str) -> Digraph: Displays the tree structure as a graph.
+- save_pdf_to_file(tree: ValueTree) -> None: Saves the tree structure as a PDF file.
+- save_raw_data_to_file(tree: ValueTree, count: str = '#') -> None: Saves the raw data of the tree
+structure to a file.
+"""
+
+# pyright: reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false
+
+import sys
+from pickle import dump
+
+from graphviz import Digraph
+from valanga import BranchKey, State
+
+from anemone.nodes import ITreeNode
+from anemone.nodes.algorithm_node.algorithm_node import (
+    AlgorithmNode,
+)
+
+from .tree import Tree
+
+
+def add_dot[StateT: State](dot: Digraph, treenode: ITreeNode[StateT]) -> None:
+    """
+    Adds a node and edges to the given Dot graph based on the provided tree node.
+
+    Args:
+        dot (Digraph): The Dot graph to add the node and edges to.
+        treenode (ITreeNode): The tree node to visualize.
+
+    Returns:
+        None
+    """
+    nd = treenode.dot_description()
+    dot.node(str(treenode.id), nd)
+    branch: BranchKey
+    for _, branch in enumerate(treenode.branches_children):
+        if treenode.branches_children[branch] is not None:
+            child = treenode.branches_children[branch]
+            if child is not None:
+                cdd = str(child.id)
+                dot.edge(
+                    str(treenode.id),
+                    cdd,
+                    str(treenode.state.branch_name_from_key(key=branch)),
+                )
+                add_dot(dot, child)
+
+
+def display_special[StateT: State](
+    node: AlgorithmNode[StateT],  # or AlgorithmNode if you prefer
+    format_str: str,
+    index: dict[BranchKey, str],
+) -> Digraph:
+    """Display a tree with custom edge labels for the given node."""
+    dot = Digraph(format=format_str)
+
+    nd = node.dot_description()
+    dot.node(str(node.id), nd)
+
+    sorted_branches: list[BranchKey] = sorted(node.branches_children.keys(), key=str)
+
+    for branch_key in sorted_branches:
+        child = node.branches_children[branch_key]
+        if child is None:
+            continue
+
+        edge_description: str = (
+            index[branch_key]
+            + "|"
+            + str(node.state.branch_name_from_key(key=branch_key))
+            + "|"
+            + node.tree_evaluation.description_tree_visualizer_branch(child)
+        )
+        dot.edge(str(node.id), str(child.id), edge_description)
+        dot.node(str(child.id), child.dot_description())
+        print("--move:", edge_description)
+        print("--child:", child.dot_description())
+
+    return dot
+
+
+def display[StateT: State](
+    tree: Tree[AlgorithmNode[StateT]], format_str: str
+) -> Digraph:
+    """
+    Display the move and value tree using graph visualization.
+
+    Args:
+        tree (Tree): The move and value tree to be displayed.
+        format_str (str): The format of the output graph (e.g., 'png', 'pdf', 'svg').
+
+    Returns:
+        Digraph: The graph representation of the move and value tree.
+    """
+    dot = Digraph(format=format_str)
+    add_dot(dot, tree.root_node)
+    return dot
+
+
+def save_pdf_to_file[StateT: State](tree: Tree[AlgorithmNode[StateT]]) -> None:
+    """
+    Saves the visualization of a tree as a PDF file.
+
+    Args:
+        tree (Tree): The tree to be visualized and saved.
+
+    Returns:
+        None
+    """
+    dot = display(tree=tree, format_str="pdf")
+    tag_ = tree.root_node.state.tag
+    dot.render("chipiron/runs/treedisplays/TreeVisual_" + str(tag_) + ".pdf")
+
+
+def save_raw_data_to_file(tree: Tree[AlgorithmNode], count: str = "#") -> None:
+    """
+    Save raw data of a ValueTree to a file.
+
+    Args:
+        tree (Tree): The Tree object to save.
+        count (str, optional): A string to append to the filename. Defaults to '#'.
+
+    Returns:
+        None
+    """
+    tag_ = tree.root_node.state.tag
+    filename = "chipiron/debugTreeData_" + str(tag_) + "-" + str(count) + ".td"
+
+    sys.setrecursionlimit(100000)
+    with open(filename, "wb") as f:
+        dump([tree.descendants, tree.root_node], f)

anemone/updates/__init__.py

@@ -0,0 +1,33 @@
+"""
+This module provides classes and functions for updating tree values in the move selector.
+
+Classes:
+- AlgorithmNodeUpdater: A class for updating algorithm nodes in the tree.
+- MinMaxEvaluationUpdater: A class for updating min-max evaluation values in the tree.
+
+Functions:
+- create_algorithm_node_updater: A function for creating an instance of AlgorithmNodeUpdater.
+
+Other:
+- UpdateInstructions: A class representing update instructions for a single node.
+- UpdateInstructionsBatch: A class representing a batch of update instructions.
+
+"""
+
+from .algorithm_node_updater import AlgorithmNodeUpdater
+from .factory import create_algorithm_node_updater
+from .minmax_evaluation_updater import MinMaxEvaluationUpdater
+from .updates_file import (
+    UpdateInstructionsFromOneNode,
+    UpdateInstructionsTowardsMultipleNodes,
+    UpdateInstructionsTowardsOneParentNode,
+)
+
+__all__ = [
+    "create_algorithm_node_updater",
+    "AlgorithmNodeUpdater",
+    "UpdateInstructionsFromOneNode",
+    "UpdateInstructionsTowardsOneParentNode",
+    "MinMaxEvaluationUpdater",
+    "UpdateInstructionsTowardsMultipleNodes",
+]

anemone/updates/algorithm_node_updater.py

@@ -0,0 +1,157 @@
+"""
+This module contains the AlgorithmNodeUpdater class, which is responsible for updating AlgorithmNode objects in a
+ tree structure.
+
+The AlgorithmNodeUpdater class provides methods for creating update instructions after a node is added to the
+ tree, generating update instructions for a batch of tree expansions, and performing updates on a specific node
+  based on the given update instructions.
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from anemone.nodes.algorithm_node.algorithm_node import (
+    AlgorithmNode,
+)
+
+from .index_updater import IndexUpdater
+from .minmax_evaluation_updater import MinMaxEvaluationUpdater
+from .updates_file import (
+    UpdateInstructionsFromOneNode,
+    UpdateInstructionsTowardsMultipleNodes,
+    UpdateInstructionsTowardsOneParentNode,
+)
+
+if TYPE_CHECKING:
+    from anemone.tree_manager.tree_expander import TreeExpansion, TreeExpansions
+
+    from .index_block import IndexUpdateInstructionsFromOneNode
+    from .value_block import ValueUpdateInstructionsFromOneNode
+
+
+@dataclass
+class AlgorithmNodeUpdater:
+    """
+    The AlgorithmNodeUpdater class is responsible for updating AlgorithmNode objects in a tree.
+
+    Attributes:
+        minmax_evaluation_updater (MinMaxEvaluationUpdater): The updater for min-max evaluation values.
+        index_updater (IndexUpdater | None): The updater for node indices, if available.
+    """
+
+    minmax_evaluation_updater: MinMaxEvaluationUpdater
+    index_updater: IndexUpdater | None = None
+
+    def create_update_instructions_after_node_birth(
+        self, new_node: AlgorithmNode
+    ) -> UpdateInstructionsFromOneNode:
+        """
+        Creates update instructions after a new node is added to the tree.
+
+        Args:
+            new_node (AlgorithmNode): The newly added AlgorithmNode.
+
+        Returns:
+            UpdateInstructions: The update instructions for the new node.
+        """
+        value_update_instructions: ValueUpdateInstructionsFromOneNode
+        value_update_instructions = (
+            self.minmax_evaluation_updater.create_update_instructions_after_node_birth(
+                new_node=new_node
+            )
+        )
+
+        index_update_instructions: IndexUpdateInstructionsFromOneNode | None
+        if self.index_updater is not None:
+            index_update_instructions = (
+                self.index_updater.create_update_instructions_after_node_birth(
+                    new_node=new_node
+                )
+            )
+        else:
+            index_update_instructions = None
+
+        update_instructions: UpdateInstructionsFromOneNode = (
+            UpdateInstructionsFromOneNode(
+                value_block=value_update_instructions,
+                index_block=index_update_instructions,
+            )
+        )
+
+        return update_instructions
+
+    def generate_update_instructions[NodeT: AlgorithmNode](
+        self, tree_expansions: "TreeExpansions[NodeT]"
+    ) -> "UpdateInstructionsTowardsMultipleNodes[NodeT]":
+        """
+        Generates update instructions for a batch of tree expansions.
+
+        Args:
+            tree_expansions (tree_man.TreeExpansions): The batch of tree expansions.
+
+        Returns:
+            UpdateInstructionsBatch: The update instructions for the batch of tree expansions.
+        """
+        # TODO is the way of merging now overkill?
+
+        update_instructions_batch: UpdateInstructionsTowardsMultipleNodes[NodeT]
+        update_instructions_batch = UpdateInstructionsTowardsMultipleNodes()
+
+        tree_expansion: "TreeExpansion[NodeT]"
+        for tree_expansion in tree_expansions:
+            update_instructions: UpdateInstructionsFromOneNode = (
+                self.create_update_instructions_after_node_birth(
+                    new_node=tree_expansion.child_node
+                )
+            )
+            # update_instructions_batch is key sorted dict, sorted by depth to ensure proper backprop from the back
+
+            assert tree_expansion.parent_node is not None
+            # looks like we should not update from the root node backward!
+
+            assert tree_expansion.branch_key is not None
+            update_instructions_batch.add_update_from_one_child_node(
+                update_from_child_node=update_instructions,
+                parent_node=tree_expansion.parent_node,
+                branch_from_parent=tree_expansion.branch_key,
+            )
+
+        return update_instructions_batch
+
+    def perform_updates(
+        self,
+        node_to_update: AlgorithmNode,
+        update_instructions: UpdateInstructionsTowardsOneParentNode,
+    ) -> UpdateInstructionsFromOneNode:
+        """
+        Performs updates on a specific node based on the given update instructions.
+
+        Args:
+            node_to_update (AlgorithmNode): The node to update.
+            update_instructions (UpdateInstructions): The update instructions for the node.
+
+        Returns:
+            UpdateInstructions: The new update instructions after performing the updates.
+        """
+        value_update_instructions: ValueUpdateInstructionsFromOneNode = (
+            self.minmax_evaluation_updater.perform_updates(
+                node_to_update, updates_instructions=update_instructions
+            )
+        )
+
+        index_update_instructions: IndexUpdateInstructionsFromOneNode | None
+        if self.index_updater is not None:
+            index_update_instructions = self.index_updater.perform_updates(
+                node_to_update, updates_instructions=update_instructions
+            )
+        else:
+            index_update_instructions = None
+
+        new_update_instructions: UpdateInstructionsFromOneNode = (
+            UpdateInstructionsFromOneNode(
+                value_block=value_update_instructions,
+                index_block=index_update_instructions,
+            )
+        )
+
+        return new_update_instructions

anemone/updates/factory.py

@@ -0,0 +1,36 @@
+"""
+This module provides a factory function to create an instance of AlgorithmNodeUpdater.
+
+The AlgorithmNodeUpdater is responsible for updating the algorithm node in a tree structure.
+
+The factory function `create_algorithm_node_updater` takes an optional `index_updater` parameter and returns an instance of AlgorithmNodeUpdater.
+
+Example usage:
+    algorithm_node_updater = create_algorithm_node_updater(index_updater)
+"""
+
+from .algorithm_node_updater import AlgorithmNodeUpdater
+from .index_updater import IndexUpdater
+from .minmax_evaluation_updater import MinMaxEvaluationUpdater
+
+
+def create_algorithm_node_updater(
+    index_updater: IndexUpdater | None,
+) -> AlgorithmNodeUpdater:
+    """
+    Creates an instance of AlgorithmNodeUpdater.
+
+    Args:
+        index_updater (IndexUpdater | None): The index updater object.
+
+    Returns:
+        AlgorithmNodeUpdater: An instance of AlgorithmNodeUpdater.
+
+    """
+    minmax_evaluation_updater: MinMaxEvaluationUpdater = MinMaxEvaluationUpdater()
+
+    algorithm_node_updater: AlgorithmNodeUpdater = AlgorithmNodeUpdater(
+        minmax_evaluation_updater=minmax_evaluation_updater, index_updater=index_updater
+    )
+
+    return algorithm_node_updater

anemone/updates/index_block.py

@@ -0,0 +1,91 @@
+"""
+This module defines the IndexUpdateInstructionsBlock class, which represents a block of update instructions for
+index values in a tree structure.
+
+The IndexUpdateInstructionsBlock class is a dataclass that contains a set of AlgorithmNode objects representing
+children with updated index values. It provides methods for merging update instructions and printing information
+about the block.
+"""
+
+from dataclasses import dataclass, field
+from typing import Self
+
+from valanga import BranchKey
+
+from anemone.nodes.algorithm_node.algorithm_node import (
+    AlgorithmNode,
+)
+
+
+@dataclass(slots=True)
+class IndexUpdateInstructionsFromOneNode:
+    """
+    Represents a block of instructions for updating an index.
+
+    Attributes:
+        node_sending_update (AlgorithmNode): The node sending the update.
+        updated_index (bool): Indicates whether the index has been updated.
+    """
+
+    node_sending_update: AlgorithmNode
+    updated_index: bool
+
+
+def _new_branches_with_updated_index() -> set[BranchKey]:
+    """Return a new set for branches with updated indices."""
+    return set()
+
+
+@dataclass(slots=True)
+class IndexUpdateInstructionsTowardsOneParentNode:
+    """
+    Represents a block of index update instructions intended to a specific node in the algorithm tree.
+
+    This class is used to store and manipulate sets of children with updated index values.
+
+    Attributes:
+        moves_with_updated_index (Set[IMove]): A set of children with updated index values.
+    """
+
+    branches_with_updated_index: set[BranchKey] = field(
+        default_factory=_new_branches_with_updated_index
+    )
+
+    def add_update_from_one_child_node(
+        self,
+        update_from_one_child_node: IndexUpdateInstructionsFromOneNode,
+        branch_from_parent_to_child: BranchKey,
+    ) -> None:
+        """Adds an update from a child node to the parent node.
+
+        Args:
+            update_from_one_child_node (IndexUpdateInstructionsFromOneNode): The update instructions from the child node.
+            move_from_parent_to_child (moveKey): The move key representing the parent's move to the child.
+        """
+        if update_from_one_child_node.updated_index:
+            self.branches_with_updated_index.add(branch_from_parent_to_child)
+
+    def add_update_toward_one_parent_node(self, another_update: Self) -> None:
+        """Adds an update from another child node to the parent node.
+
+        Args:
+            another_update (Self): The update instructions from another child node.
+        """
+        self.branches_with_updated_index = (
+            self.branches_with_updated_index
+            | another_update.branches_with_updated_index
+        )
+
+    def empty(self) -> bool:
+        """
+        Check if the IndexUpdateInstructionsBlock is empty.
+
+        Returns:
+            bool: True if the block is empty, False otherwise.
+        """
+        empty_bool = not bool(self.branches_with_updated_index)
+        return empty_bool
+
+    def print_info(self) -> None:
+        """Prints information about the moves with updated indices."""
+        print(self.branches_with_updated_index)