algorhino-anemone 0.1.1__py3-none-any.whl

anemone/node_selector/sequool/sequool.py

@@ -0,0 +1,395 @@
+"""
+Sequool
+
+This module contains the implementation of the Sequool node selector. The Sequool node selector is responsible for
+choosing the best node to open in a move tree based on various selection strategies.
+
+Classes:
+- TreeDepthSelector: Protocol defining the interface for a half-move selector.
+- StaticNotOpenedSelector: A node selector that considers the number of visits and selects half-moves based on zipf distribution.
+- RandomAllSelector: A node selector that selects half-moves randomly.
+- Sequool: The main class implementing the Sequool node selector.
+
+Functions:
+- consider_nodes_from_all_lesser_tree_depths_in_descendants: Consider all nodes in smaller half-moves than the picked half-move using the descendants object.
+- consider_nodes_from_all_lesser_tree_depths_in_sub_stree: Consider all nodes in smaller half-moves than the picked half-move using tree traversal.
+- consider_nodes_only_from_tree_depths_in_descendants: Consider only the nodes at the picked depth.
+- get_best_node_from_candidates: Get the best node from a list of candidate nodes based on their exploration index data.
+"""
+
+from dataclasses import dataclass, field
+from random import Random
+from typing import TYPE_CHECKING, Any, Callable, Protocol
+
+from anemone import trees
+from anemone.basics import TreeDepth
+from anemone.indices.node_indices.index_data import (
+    MaxDepthDescendants,
+)
+from anemone.node_selector.notations_and_statics import (
+    zipf_picks,
+    zipf_picks_random,
+)
+from anemone.node_selector.opening_instructions import (
+    OpeningInstructions,
+    OpeningInstructor,
+    create_instructions_to_open_all_branches,
+)
+from anemone.nodes.algorithm_node.algorithm_node import AlgorithmNode
+from anemone.nodes.tree_traversal import (
+    get_descendants_candidate_not_over,
+)
+from anemone.trees.descendants import Descendants
+
+if TYPE_CHECKING:
+    from anemone import tree_manager as tree_man
+
+
+class TreeDepthSelector[NodeT: AlgorithmNode[Any] = AlgorithmNode[Any]](Protocol):
+    """
+    Protocol defining the interface for a half-move selector.
+    """
+
+    def update_from_expansions(
+        self, latest_tree_expansions: "tree_man.TreeExpansions[NodeT]"
+    ) -> None:
+        """
+        Update the half-move selector with the latest tree expansions.
+
+        Args:
+            latest_tree_expansions: The latest tree expansions.
+
+        Returns:
+            None
+        """
+
+    def select_tree_depth(
+        self, from_node: NodeT, random_generator: Random
+    ) -> TreeDepth:
+        """
+        Select the next half-move to consider based on the given node and random generator.
+
+        Args:
+            from_node: The current node.
+            random_generator: The random generator.
+
+        Returns:
+            The selected half-move.
+        """
+        ...
+
+
+def _make_count_visits() -> dict[TreeDepth, int]:
+    """Helper function to create a default count visits dictionary."""
+    return {}
+
+
+count_visits: dict[TreeDepth, int] = _make_count_visits()
+
+
+@dataclass
+class StaticNotOpenedSelector[NodeT: AlgorithmNode[Any] = AlgorithmNode[Any]]:
+    """
+    A node selector that considers the number of visits and selects half-moves based on zipf distribution.
+    """
+
+    all_nodes_not_opened: Descendants[NodeT]
+
+    # counting the visits for each tree_depth
+    count_visits: dict[TreeDepth, int] = field(default_factory=_make_count_visits)
+
+    def update_from_expansions(
+        self, latest_tree_expansions: "tree_man.TreeExpansions[NodeT]"
+    ) -> None:
+        """
+        Update the node selector with the latest tree expansions.
+
+        Args:
+            latest_tree_expansions: The latest tree expansions.
+
+        Returns:
+            None
+        """
+
+        # Update internal info with the latest tree expansions
+        expansion: tree_man.TreeExpansion[NodeT]
+        for expansion in latest_tree_expansions:
+            if expansion.creation_child_node:
+                self.all_nodes_not_opened.add_descendant(expansion.child_node)
+
+            # if a new tree_depth is being created then init the visits to 1
+            # (0 would bug as it would automatically be selected with zipf computation)
+            tree_depth: int = expansion.child_node.tree_depth
+            if tree_depth not in self.count_visits:
+                self.count_visits[tree_depth] = 1
+
+    def select_tree_depth(
+        self, from_node: NodeT, random_generator: Random
+    ) -> TreeDepth:
+        """
+        Select the next half-move to consider based on the given node and random generator.
+
+        Args:
+            from_node: The current node.
+            random_generator: The random generator.
+
+        Returns:
+            The selected half-move.
+        """
+        _ = from_node  # not used here
+
+        filtered_count_visits: dict[int, int | float] = {
+            hm: value
+            for hm, value in self.count_visits.items()
+            if hm in self.all_nodes_not_opened
+        }
+
+        # choose a half move based on zipf
+        tree_depth_picked: int = zipf_picks(
+            ranks_values=filtered_count_visits,
+            random_generator=random_generator,
+            shift=True,
+            random_pick=False,
+        )
+
+        self.count_visits[tree_depth_picked] += 1
+
+        return tree_depth_picked
+
+
+type ConsiderNodesFromTreeDepths[NodeT: AlgorithmNode[Any]] = Callable[
+    [TreeDepth, NodeT],
+    list[NodeT],
+]
+
+
+def consider_nodes_from_all_lesser_tree_depths_in_descendants[N: AlgorithmNode[Any]](
+    tree_depth_picked: TreeDepth,
+    from_node: N,
+    descendants: Descendants[N],
+) -> list[N]:
+    """
+    Consider all the nodes that are in smaller half-moves than the picked half-move using the descendants object.
+
+    Args:
+        tree_depth_picked: The picked half-move.
+        from_node: The current node.
+        descendants: The descendants object.
+
+    Returns:
+        A list of nodes to consider.
+    """
+
+    _ = from_node  # not used here
+
+    nodes_to_consider: list[N] = []
+    tree_depth: int
+    # considering all half-move smaller than the half move picked
+    for tree_depth in filter(lambda hm: hm < tree_depth_picked + 1, descendants):
+        nodes_to_consider += list(descendants[tree_depth].values())
+
+    return nodes_to_consider
+
+
+def consider_nodes_from_all_lesser_tree_depths_in_sub_stree[N: AlgorithmNode[Any]](
+    tree_depth_picked: TreeDepth,
+    from_node: N,
+) -> list[N]:
+    """
+    Consider all the nodes that are in smaller half-moves than the picked half-move using tree traversal.
+
+    Args:
+        tree_depth_picked: The picked half-move.
+        from_node: The current node.
+
+    Returns:
+        A list of nodes to consider.
+    """
+
+    nodes_to_consider: list[N] = get_descendants_candidate_not_over(
+        from_tree_node=from_node, max_depth=tree_depth_picked - from_node.tree_depth
+    )
+    return nodes_to_consider
+
+
+def consider_nodes_only_from_tree_depths_in_descendants[N: AlgorithmNode[Any]](
+    tree_depth_picked: TreeDepth,
+    from_node: N,
+    descendants: Descendants[N],
+) -> list[N]:
+    """
+    Consider only the nodes at the picked depth.
+
+    Args:
+        tree_depth_picked: The picked half-move.
+        from_node: The current node.
+        descendants: The descendants object.
+
+    Returns:
+        A list of nodes to consider.
+    """
+    _ = from_node  # not used here
+    return list(descendants[tree_depth_picked].values())
+
+
+@dataclass
+class RandomAllSelector[NodeT: AlgorithmNode[Any] = AlgorithmNode[Any]]:
+    """
+    A node selector that selects half-moves randomly.
+    """
+
+    def update_from_expansions(
+        self, latest_tree_expansions: "tree_man.TreeExpansions[NodeT]"
+    ) -> None:
+        """
+        Update the node selector with the latest tree expansions.
+
+        Args:
+            latest_tree_expansions: The latest tree expansions.
+
+        Returns:
+            None
+        """
+
+    def select_tree_depth(
+        self, from_node: NodeT, random_generator: Random
+    ) -> TreeDepth:
+        """
+        Select the next half-move to consider based on the given node and random generator.
+
+        Args:
+            from_node: The current node.
+            random_generator: The random generator.
+
+        Returns:
+            The selected half-move.
+        """
+
+        tree_depth_picked: int
+        # choose a half move based on zipf
+        assert isinstance(from_node.exploration_index_data, MaxDepthDescendants)
+        max_descendants_depth: int = (
+            from_node.exploration_index_data.max_depth_descendants
+        )
+        if max_descendants_depth:
+            depth_picked: int = zipf_picks_random(
+                ordered_list_elements=list(range(1, max_descendants_depth + 1)),
+                random_generator=random_generator,
+            )
+            tree_depth_picked = from_node.tree_depth + depth_picked
+        else:
+            tree_depth_picked = from_node.tree_depth
+        return tree_depth_picked
+
+
+def get_best_node_from_candidates[N: AlgorithmNode[Any]](
+    nodes_to_consider: list[N],
+) -> N:
+    """
+    Returns the best node from a list of candidate nodes based on their exploration index and half move.
+
+    Args:
+        nodes_to_consider (list[ITreeNode]): A list of candidate nodes to consider.
+
+    Returns:
+        AlgorithmNode: The best node from the list of candidates.
+    """
+    best_node: N = nodes_to_consider[0]
+    assert best_node.exploration_index_data is not None
+    best_value = (best_node.exploration_index_data.index, best_node.tree_depth)
+
+    node: N
+    for node in nodes_to_consider:
+        assert node.exploration_index_data is not None
+        if node.exploration_index_data.index is not None:
+            assert best_node.exploration_index_data is not None
+            if (
+                best_node.exploration_index_data.index is None
+                or (node.exploration_index_data.index, node.tree_depth) < best_value
+            ):
+                best_node = node
+                best_value = (node.exploration_index_data.index, node.tree_depth)
+    return best_node
+
+
+@dataclass
+class Sequool[NodeT: AlgorithmNode[Any] = AlgorithmNode[Any]]:
+    """
+    The main class implementing the Sequool node selector.
+    """
+
+    opening_instructor: OpeningInstructor
+    all_nodes_not_opened: Descendants[NodeT]
+    recursif: bool
+    random_depth_pick: bool
+    tree_depth_selector: TreeDepthSelector[NodeT]
+    random_generator: Random
+    consider_nodes_from_tree_depths: ConsiderNodesFromTreeDepths[NodeT]
+
+    def choose_node_and_branch_to_open(
+        self,
+        tree: trees.Tree[NodeT],
+        latest_tree_expansions: "tree_man.TreeExpansions[NodeT]",
+    ) -> OpeningInstructions[NodeT]:
+        """
+        Choose the best node to open in the move tree and return the opening instructions.
+
+        Args:
+            tree: The move tree.
+            latest_tree_expansions: The latest tree expansions.
+
+        Returns:
+            The opening instructions.
+        """
+
+        self.tree_depth_selector.update_from_expansions(
+            latest_tree_expansions=latest_tree_expansions
+        )
+
+        opening_instructions: OpeningInstructions[NodeT] = (
+            self.choose_node_and_move_to_open_recur(from_node=tree.root_node)
+        )
+
+        return opening_instructions
+
+    def choose_node_and_move_to_open_recur(
+        self, from_node: NodeT
+    ) -> OpeningInstructions[NodeT]:
+        """
+        Recursively choose the best node to open in the move tree and return the opening instructions.
+
+        Args:
+            from_node: The current node.
+
+        Returns:
+            The opening instructions.
+        """
+
+        tree_depth_selected: TreeDepth = self.tree_depth_selector.select_tree_depth(
+            from_node=from_node, random_generator=self.random_generator
+        )
+
+        nodes_to_consider: list[NodeT] = self.consider_nodes_from_tree_depths(
+            tree_depth_selected, from_node
+        )
+
+        best_node: NodeT = get_best_node_from_candidates(
+            nodes_to_consider=nodes_to_consider
+        )
+
+        if not self.recursif:
+            self.all_nodes_not_opened.remove_descendant(best_node)
+
+        if self.recursif and best_node.tree_node.all_branches_generated:
+            return self.choose_node_and_move_to_open_recur(from_node=best_node)
+
+        all_branches_to_open = self.opening_instructor.all_branches_to_open(
+            node_to_open=best_node
+        )
+        opening_instructions: OpeningInstructions[NodeT] = (
+            create_instructions_to_open_all_branches(
+                branches_to_play=all_branches_to_open, node_to_open=best_node
+            )
+        )
+
+        return opening_instructions

anemone/node_selector/uniform/__init__.py

@@ -0,0 +1,16 @@
+"""
+This module provides a uniform selection strategy for nodes in a tree.
+
+The Uniform selection strategy selects nodes uniformly at random from the available options.
+
+Example usage:
+    from .uniform import Uniform
+
+    uniform_selector = Uniform()
+    selected_node = uniform_selector.select_node(nodes)
+
+"""
+
+from .uniform import Uniform
+
+__all__ = ["Uniform"]

anemone/node_selector/uniform/uniform.py

@@ -0,0 +1,113 @@
+"""
+This module contains the implementation of the Uniform Node selector.
+
+The Uniform Node selector is responsible for selecting nodes to expand in a tree-based move selector algorithm.
+It uses an opening instructor to determine the moves to open for each node and generates opening instructions accordingly.
+
+Classes:
+- Uniform: The Uniform Node selector class.
+
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from anemone import tree_manager as tree_man
+from anemone import trees
+from anemone.node_selector.opening_instructions import (
+    OpeningInstructions,
+    OpeningInstructor,
+    create_instructions_to_open_all_branches,
+)
+from anemone.nodes.algorithm_node import AlgorithmNode
+
+if TYPE_CHECKING:
+    from valanga import BranchKey
+
+
+class Uniform[NodeT: AlgorithmNode[Any] = AlgorithmNode[Any]]:
+    """The Uniform Node selector"""
+
+    opening_instructor: OpeningInstructor
+
+    def __init__(self, opening_instructor: OpeningInstructor) -> None:
+        """
+        Initializes a new instance of the Uniform class.
+
+        Args:
+        - opening_instructor (OpeningInstructor): The opening instructor to be used for determining moves to open.
+
+        """
+        self.opening_instructor = opening_instructor
+        self.current_depth_to_expand = 0
+
+    def get_current_depth_to_expand(self) -> int:
+        """
+        Gets the current depth to expand.
+
+        Returns:
+        - int: The current depth to expand.
+
+        """
+        return self.current_depth_to_expand
+
+    def choose_node_and_branch_to_open(
+        self,
+        tree: trees.Tree[NodeT],
+        latest_tree_expansions: tree_man.TreeExpansions[NodeT],
+    ) -> OpeningInstructions[NodeT]:
+        """
+        Chooses a node to expand and determines the moves to open for that node.
+
+        Args:
+        - tree (trees.Tree[AlgorithmNode]): The move and value tree.
+        - latest_tree_expansions (tree_man.TreeExpansions): The latest tree expansions.
+
+        Returns:
+        - OpeningInstructions: The opening instructions for the chosen node.
+
+        """
+        _ = latest_tree_expansions  # not used here
+
+        opening_instructions_batch: OpeningInstructions[NodeT] = OpeningInstructions()
+
+        # generate the nodes to expand
+        current_half_move_to_expand = (
+            tree.tree_root_tree_depth + self.current_depth_to_expand
+        )
+
+        # self.tree.descendants.print_info()
+        nodes_to_consider = list(tree.descendants[current_half_move_to_expand].values())
+
+        # filter the game-over ones and the ones with values
+        nodes_to_consider_not_over: list[NodeT] = [
+            node for node in nodes_to_consider if not node.is_over()
+        ]
+
+        # sort them by order of importance for the player
+        nodes_to_consider_sorted_by_value = sorted(
+            nodes_to_consider_not_over,
+            key=lambda x: tree.root_node.tree_evaluation.subjective_value_of(
+                x.tree_evaluation
+            ),
+        )  # best last
+
+        for node in nodes_to_consider_sorted_by_value:
+            all_branches_to_open: list[BranchKey] = (
+                self.opening_instructor.all_branches_to_open(node_to_open=node)
+            )
+            opening_instructions: OpeningInstructions[NodeT] = (
+                create_instructions_to_open_all_branches(
+                    branches_to_play=all_branches_to_open, node_to_open=node
+                )
+            )
+            opening_instructions_batch.merge(opening_instructions)
+
+        self.current_depth_to_expand += 1
+        return opening_instructions_batch
+
+    def print_info(self) -> None:
+        """
+        Prints information about the Uniform Node selector.
+
+        """
+        print("Uniform")

anemone/nodes/__init__.py

@@ -0,0 +1,15 @@
+"""
+This module contains the implementation of tree nodes for move selection.
+
+The tree nodes are used in the move selector to represent different moves and their values.
+
+Classes:
+- TreeNode: Represents a tree node for move selection.
+- ITreeNode: Interface for tree nodes.
+
+"""
+
+from .itree_node import ITreeNode
+from .tree_node import TreeNode
+
+__all__ = ["TreeNode", "ITreeNode"]

anemone/nodes/algorithm_node/__init__.py

@@ -0,0 +1,7 @@
+"""
+init file for algorithm_node module
+"""
+
+from .algorithm_node import AlgorithmNode
+
+__all__ = ["AlgorithmNode"]