algorhino-anemone 0.1.1__py3-none-any.whl

anemone/node_evaluation/node_tree_evaluation/node_tree_evaluation.py

@@ -0,0 +1,137 @@
+from typing import TYPE_CHECKING, Protocol, Self
+
+from valanga import (
+    BoardEvaluation,
+    BranchKey,
+    OverEvent,
+    State,
+)
+
+type BranchSortValue = tuple[float, int, int]
+
+
+if TYPE_CHECKING:
+    from anemone.nodes.itree_node import ITreeNode
+
+
+class NodeTreeEvaluation[StateT: State = State](Protocol):
+    """
+    Interface for Node Tree Evaluation
+    This is the evaluation of a node that is based both on a direct evaluation of the state within and of the NodeTreeEvaluation
+    and its children.
+    The direct evaluation is used to evaluate leaf nodes, while the children evaluations are used to propagate values up the tree.
+
+    """
+
+    # absolute value wrt to white player as estimated by a state evaluator
+    value_white_direct_evaluation: float | None = None
+
+    # creating a base Over event that is set to None
+    over_event: OverEvent
+
+    # the list of branches that have not yet be found to be over
+    # using atm a list instead of set as atm python set are not insertion ordered which adds randomness
+    # and makes debug harder
+    branches_not_over: list[BranchKey]
+
+    branches_sorted_by_value_: dict[BranchKey, BranchSortValue]
+
+    best_branch_sequence: list[BranchKey]
+
+    # absolute value wrt to white player as computed from the value_white_* of the descendants
+    # of this node (self) by a minmax procedure.
+    value_white_minmax: float | None = None
+
+    def set_evaluation(self, evaluation: float) -> None:
+        """sets the evaluation from the board evaluator
+
+        Args:
+            evaluation (float): The evaluation value to be set.
+
+        Returns:
+            None
+        """
+        ...
+
+    def is_over(self) -> bool:
+        """
+        Checks if the game is over.
+
+        Returns:
+            bool: True if the game is over, False otherwise.
+        """
+        ...
+
+    def dot_description(self) -> str:
+        """
+        Returns a string representation of the node's description in DOT format.
+
+        The description includes the values of `value_white_minmax` and `value_white_evaluator`,
+        as well as the best branch sequence and the over event tag.
+
+        Returns:
+            A string representation of the node's description in DOT format.
+        """
+        ...
+
+    def update_best_branch_sequence(
+        self, branches_with_updated_best_branch_seq: set[BranchKey]
+    ) -> bool:
+        """Update the best branch sequence from updated branches."""
+        ...
+
+    def minmax_value_update_from_children(
+        self, branches_with_updated_value: set[BranchKey]
+    ) -> tuple[bool, bool]:
+        """Update minmax value from children and return update flags."""
+        ...
+
+    def update_over(self, branches_with_updated_over: set[BranchKey]) -> bool:
+        """Update terminal state based on updated branches."""
+        ...
+
+    def evaluate(self) -> BoardEvaluation:
+        """Return a board evaluation for this node."""
+        ...
+
+    def description_tree_visualizer_branch(self, child: "ITreeNode[StateT]") -> str:
+        """Return a visualization label for a child branch."""
+        ...
+
+    def print_best_line(self) -> None:
+        """Print the current best line."""
+        ...
+
+    def get_value_white(self) -> float:
+        """Return the current white evaluation value."""
+        ...
+
+    def best_branch(self) -> BranchKey | None:
+        """Return the current best branch key."""
+        ...
+
+    def second_best_branch(self) -> BranchKey:
+        """Return the second-best branch key."""
+        ...
+
+    def print_branches_sorted_by_value(self) -> None:
+        """Print branches sorted by value."""
+        ...
+
+    def print_branches_sorted_by_value_and_exploration(self) -> None:
+        """Print branches sorted by value and exploration metrics."""
+        ...
+
+    def get_all_of_the_best_branches(
+        self, how_equal: str | None = None
+    ) -> list[BranchKey]:
+        """Return all best branches according to an equality rule."""
+        ...
+
+    def subjective_value_of(self, another_node_eval: Self) -> float:
+        """Return this node's value relative to another evaluation."""
+        ...
+
+    def sort_branches_not_over(self) -> list[BranchKey]:
+        """Return branches not over, sorted by evaluation."""
+        ...

anemone/node_evaluation/node_tree_evaluation/node_tree_evaluation_factory.py

@@ -0,0 +1,43 @@
+from typing import Any, Protocol
+
+from valanga import State, TurnState
+
+from anemone.node_evaluation.node_tree_evaluation.node_minmax_evaluation import (
+    NodeMinmaxEvaluation,
+)
+from anemone.node_evaluation.node_tree_evaluation.node_tree_evaluation import (
+    NodeTreeEvaluation,
+)
+from anemone.nodes.tree_node import TreeNode
+
+
+class NodeTreeMinmaxEvaluationFactory[StateT: TurnState]:
+    """
+    The class creating Node Evaluations including children
+    """
+
+    def create(
+        self,
+        tree_node: TreeNode[Any, StateT],
+    ) -> NodeMinmaxEvaluation[Any, StateT]:
+        """
+        Creates a new NodeEvaluationIncludingChildren object.
+
+        Args:
+            tree_node (TreeNode): The tree node for which the evaluation is created.
+
+        Returns:
+            NodeEvaluationIncludingChildren: The newly created NodeEvaluationIncludingChildren object.
+        """
+        return NodeMinmaxEvaluation(tree_node=tree_node)
+
+
+class NodeTreeEvaluationFactory[StateT2: State = State](Protocol):
+    """The class creating Node Evaluations including children."""
+
+    def create(
+        self,
+        tree_node: TreeNode[Any, StateT2],
+    ) -> NodeTreeEvaluation[StateT2]:
+        """Create a NodeTreeEvaluation instance for the given node."""
+        ...

anemone/node_factory/__init__.py

@@ -0,0 +1,14 @@
+"""
+This module provides the node factory classes for creating tree nodes in the move selector algorithm.
+
+The available classes in this module are:
+- TreeNodeFactory: A base class for creating tree nodes.
+- Base: A base class for the node factory classes.
+- create_node_factory: A function for creating a node factory.
+- AlgorithmNodeFactory: A node factory class for the move selector algorithm.
+"""
+
+from .algorithm_node_factory import AlgorithmNodeFactory
+from .base import TreeNodeFactory
+
+__all__ = ["TreeNodeFactory", "AlgorithmNodeFactory"]

anemone/node_factory/algorithm_node_factory.py

@@ -0,0 +1,123 @@
+""" "
+AlgorithmNodeFactory
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from valanga import (
+    BranchKey,
+    ContentRepresentation,
+    RepresentationFactory,
+    State,
+    StateModifications,
+)
+
+from anemone.basics import TreeDepth
+from anemone.indices import node_indices
+from anemone.node_evaluation.node_tree_evaluation.node_tree_evaluation_factory import (
+    NodeTreeEvaluationFactory,
+)
+from anemone.node_factory.base import TreeNodeFactory
+from anemone.nodes.algorithm_node.algorithm_node import (
+    AlgorithmNode,
+)
+from anemone.nodes.tree_node import TreeNode
+
+if TYPE_CHECKING:
+    from anemone.node_evaluation.node_tree_evaluation.node_tree_evaluation import (
+        NodeTreeEvaluation,
+    )
+
+
+@dataclass
+class AlgorithmNodeFactory[StateT: State = State]:
+    """
+    The classe creating Algorithm Nodes
+    """
+
+    tree_node_factory: TreeNodeFactory[AlgorithmNode[StateT], StateT]
+    state_representation_factory: RepresentationFactory | None
+    node_tree_evaluation_factory: NodeTreeEvaluationFactory[StateT]
+    exploration_index_data_create: node_indices.ExplorationIndexDataFactory[
+        AlgorithmNode[StateT], StateT
+    ]
+
+    def create_from_tree_node(
+        self,
+        tree_node: TreeNode[AlgorithmNode[StateT], StateT],
+        parent_node: AlgorithmNode[StateT] | None,
+        modifications: StateModifications | None,
+    ) -> AlgorithmNode[StateT]:
+        """Build an AlgorithmNode from an existing TreeNode."""
+        tree_evaluation: NodeTreeEvaluation[StateT] = (
+            self.node_tree_evaluation_factory.create(
+                tree_node=tree_node,
+            )
+        )
+
+        exploration_index_data: (
+            node_indices.NodeExplorationData[AlgorithmNode[StateT], StateT] | None
+        ) = self.exploration_index_data_create(tree_node)
+
+        state_representation: ContentRepresentation | None = None
+        if self.state_representation_factory is not None:
+            if parent_node is not None:
+                parent_node_representation = parent_node.state_representation
+            else:
+                parent_node_representation = None
+
+            state_representation = (
+                self.state_representation_factory.create_from_transition(
+                    state=tree_node.state,
+                    previous_state_representation=parent_node_representation,
+                    modifications=modifications,
+                )
+            )
+
+        return AlgorithmNode(
+            tree_node=tree_node,
+            tree_evaluation=tree_evaluation,
+            exploration_index_data=exploration_index_data,
+            state_representation=state_representation,
+        )
+
+    def create(
+        self,
+        state: StateT,
+        tree_depth: TreeDepth,
+        count: int,
+        parent_node: AlgorithmNode[StateT] | None,
+        branch_from_parent: BranchKey | None,
+        modifications: StateModifications | None,
+    ) -> AlgorithmNode[StateT]:
+        """
+        Creates an AlgorithmNode object.
+
+        Args:
+            branch_from_parent (BranchKey | None): the move that led to the node from the parent node
+            state: The state object.
+            tree_depth: The tree depth.
+            count: The count.
+            parent_node: The parent node object.
+            modifications: The board modifications object.
+
+        Returns:
+            An AlgorithmNode object.
+
+        """
+        tree_node: TreeNode[AlgorithmNode[StateT], StateT] = (
+            self.tree_node_factory.create(
+                state=state,
+                tree_depth=tree_depth,
+                count=count,
+                branch_from_parent=branch_from_parent,
+                parent_node=parent_node,
+            )
+        )
+
+        return self.create_from_tree_node(
+            tree_node=tree_node,
+            parent_node=parent_node,
+            modifications=modifications,
+        )

anemone/node_factory/base.py

@@ -0,0 +1,76 @@
+"""
+Basic class for Creating Tree nodes
+"""
+
+from typing import Any, Protocol
+
+from valanga import BranchKey, State, StateModifications
+
+from anemone.basics import TreeDepth
+from anemone.nodes.itree_node import ITreeNode
+from anemone.nodes.tree_node import TreeNode
+
+
+class NodeFactory[NodeT: ITreeNode[Any] = ITreeNode[Any]](Protocol):
+    """
+    Node Factory
+    """
+
+    def create(
+        self,
+        state: State,
+        tree_depth: TreeDepth,
+        count: int,
+        parent_node: NodeT | None,
+        branch_from_parent: BranchKey | None,
+        modifications: StateModifications | None,
+    ) -> NodeT:
+        """Create a node from state and tree metadata."""
+        ...
+
+
+class TreeNodeFactory[T: ITreeNode[Any] = ITreeNode[Any], StateT: State = State]:
+    """
+    Basic class for Creating Tree nodes
+    """
+
+    def create(
+        self,
+        state: StateT,
+        tree_depth: TreeDepth,
+        count: int,
+        parent_node: T | None,
+        branch_from_parent: BranchKey | None,
+        modifications: StateModifications | None = None,
+    ) -> TreeNode[T, StateT]:
+        """
+        Creates a new TreeNode object.
+
+        Args:
+            board (boards.BoardChi): The current board state.
+            half_move (int): The half-move count.
+            count (int): The ID of the new node.
+            parent_node (ITreeNode | None): The parent node of the new node.
+            move_from_parent (chess.Move | None): The move that leads to the new node.
+
+        Returns:
+            TreeNode: The newly created TreeNode object.
+        """
+
+        # TreeNode doesn't use modifications (it's a pure data container).
+        _ = modifications
+
+        parent_nodes: dict[T, BranchKey]
+        if parent_node is None:
+            parent_nodes = {}
+        else:
+            assert branch_from_parent is not None
+            parent_nodes = {parent_node: branch_from_parent}
+
+        tree_node: TreeNode[T, StateT] = TreeNode[T, StateT](
+            state_=state,
+            tree_depth_=tree_depth,
+            id_=count,
+            parent_nodes_=parent_nodes,
+        )
+        return tree_node

anemone/node_selector/__init__.py

@@ -0,0 +1,32 @@
+"""
+This module provides classes and functions for selecting nodes in a tree structure.
+
+The module includes the following components:
+- `create`: A factory function for creating node selectors.
+- `AllNodeSelectorArgs`: A class that represents all possible arguments for node selectors.
+- `NodeSelector`: A class that represents a node selector.
+- `NodeSelectorArgs`: A class that represents the arguments for a node selector.
+- `NodeSelectorType`: An enumeration of different types of node selectors.
+- `OpeningInstructions`: A class that represents opening instructions for node selectors.
+- `OpeningInstruction`: A class that represents an opening instruction for node selectors.
+- `OpeningType`: An enumeration of different types of opening instructions.
+
+To use this module, import it and use the provided classes and functions as needed.
+"""
+
+from .factory import AllNodeSelectorArgs, create
+from .node_selector import NodeSelector
+from .node_selector_args import NodeSelectorArgs
+from .node_selector_types import NodeSelectorType
+from .opening_instructions import OpeningInstruction, OpeningInstructions, OpeningType
+
+__all__ = [
+    "OpeningInstructions",
+    "OpeningInstruction",
+    "AllNodeSelectorArgs",
+    "OpeningType",
+    "NodeSelector",
+    "create",
+    "NodeSelectorArgs",
+    "NodeSelectorType",
+]

anemone/node_selector/branch_explorer.py

@@ -0,0 +1,89 @@
+"""
+This module contains the branchExplorer class and its subclasses.
+branchExplorer is responsible for exploring branches in a game tree.
+"""
+
+from enum import Enum
+from random import Random
+from typing import Any
+
+from valanga import BranchKey
+
+from anemone.node_selector.notations_and_statics import (
+    zipf_picks_random,
+)
+from anemone.nodes.algorithm_node import AlgorithmNode
+
+
+class SamplingPriorities(str, Enum):
+    """
+    Enumeration class representing the sampling priorities for branch exploration.
+
+    Attributes:
+        NO_PRIORITY (str): No priority for branch sampling.
+        PRIORITY_BEST (str): Priority for the best branch.
+        PRIORITY_TWO_BEST (str): Priority for the two best branches.
+    """
+
+    NO_PRIORITY = "no_priority"
+    PRIORITY_BEST = "priority_best"
+    PRIORITY_TWO_BEST = "priority_two_best"
+
+
+class BranchExplorer:
+    """
+    BranchExplorer is responsible for exploring branches in a game tree.
+    It provides a method to sample a child node to explore.
+    """
+
+    priority_sampling: SamplingPriorities
+
+    def __init__(self, priority_sampling: SamplingPriorities):
+        """
+        Initializes a branchExplorer instance.
+
+        Args:
+            priority_sampling (SamplingPriorities): The priority sampling strategy to use.
+        """
+        self.priority_sampling = priority_sampling
+
+
+class ZipfBranchExplorer(BranchExplorer):
+    """
+    ZipfBranchExplorer is a subclass of BranchExplorer that uses the Zipf distribution for sampling.
+    """
+
+    def __init__(
+        self, priority_sampling: SamplingPriorities, random_generator: Random
+    ) -> None:
+        """
+        Initializes a ZipfbranchExplorer instance.
+
+        Args:
+            priority_sampling (SamplingPriorities): The priority sampling strategy to use.
+            random_generator (Random): The random number generator to use.
+        """
+        super().__init__(priority_sampling)
+        self.random_generator = random_generator
+
+    def sample_branch_to_explore(
+        self, tree_node_to_sample_from: AlgorithmNode[Any]
+    ) -> BranchKey:
+        """
+        Samples a child node to explore from the given tree node.
+
+        Args:
+            tree_node_to_sample_from (AlgorithmNode): The tree node to sample from.
+
+        Returns:
+            AlgorithmNode: The sampled child node to explore.
+        """
+        sorted_not_over_branches: list[BranchKey] = (
+            tree_node_to_sample_from.tree_evaluation.sort_branches_not_over()
+        )
+
+        branch = zipf_picks_random(
+            ordered_list_elements=sorted_not_over_branches,
+            random_generator=self.random_generator,
+        )
+        return branch

anemone/node_selector/factory.py

@@ -0,0 +1,65 @@
+"""
+Factory to build node selectors
+"""
+
+from dataclasses import dataclass
+from random import Random
+from typing import Literal, TypeAlias
+
+from .node_selector import NodeSelector
+from .node_selector_types import NodeSelectorType
+from .opening_instructions import OpeningInstructor
+from .recurzipf.recur_zipf_base import RecurZipfBase, RecurZipfBaseArgs
+from .sequool import SequoolArgs, create_sequool
+from .uniform import Uniform
+
+
+@dataclass
+class UniformArgs:
+    """
+    Arguments for the Uniform node selector.
+
+    """
+
+    type: Literal[NodeSelectorType.UNIFORM]
+
+
+AllNodeSelectorArgs: TypeAlias = RecurZipfBaseArgs | SequoolArgs | UniformArgs
+
+
+def create(
+    args: AllNodeSelectorArgs,
+    opening_instructor: OpeningInstructor,
+    random_generator: Random,
+) -> NodeSelector:
+    """
+    Creation of a node selector
+    """
+
+    node_move_opening_selector: NodeSelector
+
+    match args.type:
+        case NodeSelectorType.UNIFORM:
+            node_move_opening_selector = Uniform(opening_instructor=opening_instructor)
+        case NodeSelectorType.RECUR_ZIPF_BASE:
+            assert isinstance(args, RecurZipfBaseArgs)
+            node_move_opening_selector = RecurZipfBase(
+                args=args,
+                random_generator=random_generator,
+                opening_instructor=opening_instructor,
+            )
+
+        case NodeSelectorType.SEQUOOL:
+            assert isinstance(args, SequoolArgs)
+            node_move_opening_selector = create_sequool(
+                opening_instructor=opening_instructor,
+                random_generator=random_generator,
+                args=args,
+            )
+
+        case _:
+            raise ValueError(
+                f"node selector construction: can not find {args.type}  {args} in file {__name__}"
+            )
+
+    return node_move_opening_selector

anemone/node_selector/node_selector.py

@@ -0,0 +1,44 @@
+"""
+This module contains the definition of the NodeSelector class and related types.
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol
+
+from anemone import trees
+from anemone.nodes.algorithm_node.algorithm_node import AlgorithmNode
+
+from .opening_instructions import OpeningInstructions
+
+if TYPE_CHECKING:
+    from anemone import tree_manager as tree_man
+
+
+@dataclass
+class NodeSelectorState:
+    """Node Selector State"""
+
+    ...
+
+
+class NodeSelector[NodeT: AlgorithmNode[Any] = AlgorithmNode[Any]](Protocol):
+    """
+    Protocol for Node Selectors.
+    """
+
+    def choose_node_and_branch_to_open(
+        self,
+        tree: trees.Tree[NodeT],
+        latest_tree_expansions: "tree_man.TreeExpansions[NodeT]",
+    ) -> OpeningInstructions[NodeT]:
+        """
+        Selects a node from the given tree and returns the instructions to move to an open position.
+
+        Args:
+            tree: The tree containing the nodes.
+            latest_tree_expansions: The latest expansions of the tree.
+
+        Returns:
+            OpeningInstructions: The instructions to move to an open position.
+        """
+        raise NotImplementedError()

anemone/node_selector/node_selector_args.py

@@ -0,0 +1,22 @@
+"""
+This module defines the NodeSelectorArgs class, which represents the arguments for a node selector.
+
+The NodeSelectorArgs class is a dataclass that contains a single attribute:
+- type: The type of the node selector, represented by the NodeSelectorType enum.
+
+Example usage:
+    args = NodeSelectorArgs(type=NodeSelectorType.BEST)
+"""
+
+from dataclasses import dataclass
+
+from .node_selector_types import NodeSelectorType
+
+
+@dataclass
+class NodeSelectorArgs:
+    """
+    Represents the arguments for a node selector.
+    """
+
+    type: NodeSelectorType

anemone/node_selector/node_selector_types.py

@@ -0,0 +1,15 @@
+"""
+This module defines the NodeSelectorType enumeration, which represents the types of node selectors.
+"""
+
+from enum import Enum
+
+
+class NodeSelectorType(str, Enum):
+    """
+    Enumeration representing the types of node selectors.
+    """
+
+    RECUR_ZIPF_BASE = "RecurZipfBase"
+    SEQUOOL = "Sequool"
+    UNIFORM = "Uniform"