algorhino-anemone 0.1.1__py3-none-any.whl

anemone/indices/node_indices/index_data.py

@@ -0,0 +1,166 @@
+"""
+Module that contains the classes for the exploration data of a tree node.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from valanga import State
+
+from anemone.nodes.itree_node import ITreeNode
+from anemone.nodes.tree_node import TreeNode
+from anemone.utils.small_tools import Interval
+
+
+@dataclass
+class NodeExplorationData[
+    Node: ITreeNode[Any] = ITreeNode[Any],
+    StateT: State = State,
+]:
+    """
+    Represents the exploration data for a tree node.
+
+    Attributes:
+        tree_node (TreeNode): The tree node associated with the exploration data.
+        index (float | None): The index value associated with the node. Defaults to None.
+
+    Methods:
+        dot_description(): Returns a string representation of the exploration data for dot visualization.
+    """
+
+    tree_node: TreeNode[Node, StateT]
+    index: float | None = None
+
+    def dot_description(self) -> str:
+        """
+        Returns a string representation of the dot description for the index.
+
+        Returns:
+            str: The dot description of the index.
+        """
+        return f"index:{self.index}"
+
+
+@dataclass
+class RecurZipfQuoolExplorationData[
+    Node: ITreeNode[Any] = ITreeNode[Any],
+    StateT: State = State,
+](NodeExplorationData[Node, StateT]):
+    """
+    Represents the exploration data for a tree node with recursive zipf-quool factor.
+
+    Attributes:
+        zipf_factored_proba (float | None): The probability associated with the node, factored by zipf-quool factor.
+            Defaults to None.
+
+    Methods:
+        dot_description(): Returns a string representation of the exploration data for dot visualization.
+    """
+
+    # the 'proba' associated by recursively multiplying 1/rank of the node with the max zipf_factor of the parents
+    zipf_factored_proba: float | None = None
+
+    def dot_description(self) -> str:
+        """
+        Returns a string representation of the index and zipf_factored_proba values.
+
+        Returns:
+            str: A string representation of the index and zipf_factored_proba values.
+        """
+        return f"index:{self.index} zipf_factored_proba:{self.zipf_factored_proba}"
+
+
+@dataclass
+class MinMaxPathValue[
+    Node: ITreeNode[Any] = ITreeNode[Any],
+    StateT: State = State,
+](NodeExplorationData[Node, StateT]):
+    """
+    Represents the exploration data for a tree node with minimum and maximum path values.
+
+    Attributes:
+        min_path_value (float | None): The minimum path value associated with the node. Defaults to None.
+        max_path_value (float | None): The maximum path value associated with the node. Defaults to None.
+
+    Methods:
+        dot_description(): Returns a string representation of the exploration data for dot visualization.
+    """
+
+    min_path_value: float | None = None
+    max_path_value: float | None = None
+
+    def dot_description(self) -> str:
+        """Return a string representation of min/max path values."""
+        return f"min_path_value: {self.min_path_value}, max_path_value: {self.max_path_value}"
+
+
+@dataclass
+class IntervalExplo[
+    Node: ITreeNode[Any] = ITreeNode[Any],
+    StateT: State = State,
+](NodeExplorationData[Node, StateT]):
+    """
+    Represents the exploration data for a tree node with an interval.
+
+    Attributes:
+        interval (Interval | None): The interval associated with the node. Defaults to None.
+
+    Methods:
+        dot_description(): Returns a string representation of the exploration data for dot visualization.
+    """
+
+    interval: Interval | None = field(default_factory=Interval)
+
+    def dot_description(self) -> str:
+        """
+        Returns a string representation of the interval values.
+
+        If the interval is None, returns 'None'.
+        Otherwise, returns a string in the format 'min_interval_value: {min_value}, max_interval_value: {max_value}'.
+
+        Returns:
+            str: A string representation of the interval values.
+        """
+        if self.interval is None:
+            return "None"
+        return f"min_interval_value: {self.interval.min_value}, max_interval_value: {self.interval.max_value}"
+
+
+@dataclass
+class MaxDepthDescendants[
+    Node: ITreeNode[Any] = ITreeNode[Any],
+    StateT: State = State,
+](NodeExplorationData[Node, StateT]):
+    """
+    Represents the exploration data for a tree node with maximum depth of descendants.
+    """
+
+    max_depth_descendants: int = 0
+
+    def update_from_child(self, child_max_depth_descendants: int) -> bool:
+        """
+        Updates the max_depth_descendants value based on the child's max_depth_descendants.
+
+        Args:
+            child_max_depth_descendants (int): The max_depth_descendants value of the child node.
+
+        Returns:
+            bool: True if the max_depth_descendants value has changed, False otherwise.
+        """
+        previous_index = self.max_depth_descendants
+        new_index: int = max(
+            self.max_depth_descendants, child_max_depth_descendants + 1
+        )
+        self.max_depth_descendants = new_index
+        has_index_changed: bool = new_index != previous_index
+
+        return has_index_changed
+
+    def dot_description(self) -> str:
+        """
+        Returns a string representation of the dot description for the node indices.
+
+        Returns:
+            str: The dot description for the node indices.
+        """
+        return f"max_depth_descendants: {self.max_depth_descendants}"

anemone/indices/node_indices/index_types.py

@@ -0,0 +1,20 @@
+"""
+This module defines the enumeration for index computation types.
+"""
+
+from enum import Enum
+
+
+class IndexComputationType(str, Enum):
+    """
+    Enumeration for index computation types.
+
+    Attributes:
+        MinGlobalChange (str): Represents the minimum global change computation type.
+        MinLocalChange (str): Represents the minimum local change computation type.
+        RecurZipf (str): Represents the recurzipf computation type.
+    """
+
+    MIN_GLOBAL_CHANGE = "min_global_change"
+    MIN_LOCAL_CHANGE = "min_local_change"
+    RECUR_ZIPF = "recurzipf"

anemone/nn/torch_evaluator.py

@@ -0,0 +1,108 @@
+"""
+Torch-based MasterStateEvaluator for efficient batch evaluations.
+"""
+# pyright: reportMissingImports=false
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Sequence
+
+from valanga import State
+from valanga.evaluations import EvalItem
+
+from anemone.node_evaluation.node_direct_evaluation.node_direct_evaluator import (
+    MasterStateEvaluator,
+    OverEventDetector,
+)
+
+if TYPE_CHECKING:
+    from coral.neural_networks.nn_content_evaluator import NNContentEvaluator
+    from torch import Tensor
+
+
+@dataclass(slots=True)
+class TorchMasterNNStateEvaluator(MasterStateEvaluator):
+    """
+    Torch-backed MasterStateEvaluator that supports efficient batch evaluation.
+    This lives in an optional module so anemone core has no torch dependency.
+    """
+
+    over: OverEventDetector
+    state_evaluator: "NNContentEvaluator"
+    device: str = "cpu"
+    script: bool = True
+
+    def __post_init__(self) -> None:
+        """Initialize the torch model and validate dependencies."""
+        try:
+            import torch
+        except ModuleNotFoundError as e:
+            raise ModuleNotFoundError(
+                "TorchMasterNNStateEvaluator requires 'torch'. "
+                "Install the optional torch dependencies."
+            ) from e
+
+        self._torch = torch
+
+        model = self.state_evaluator.net
+        self._model = torch.jit.script(model) if self.script else model
+        self._model.eval()
+
+    def value_white(self, state: State) -> float:
+        """Evaluate a single state by delegating to the batch path."""
+        # Slow path: evaluate a single state by wrapping it as an EvalItem.
+        return self.value_white_batch_items([_SingleEvalItem(state)])[0]
+
+    def value_white_batch_items[ItemStateT: State](
+        self, items: Sequence[EvalItem[ItemStateT]]
+    ) -> list[float]:
+        """Evaluate a batch of items with torch and return white values."""
+        torch = self._torch
+
+        xs: list["Tensor"] = []
+        states: list[ItemStateT] = []
+
+        for it in items:
+            st = it.state
+            states.append(st)
+
+            # Prefer precomputed representation when available
+            if it.state_representation is not None:
+                raw = it.state_representation.get_evaluator_input(state=st)
+            else:
+                raw = self.state_evaluator.content_to_input_convert(st)
+
+            xs.append(torch.as_tensor(raw).to(self.device))
+
+        x_batch = torch.stack(xs, dim=0)
+
+        with torch.no_grad():
+            out = self._model(x_batch)
+
+        converter = self.state_evaluator.output_and_value_converter
+
+        values: list[float] = []
+        for i, st in enumerate(states):
+            state_eval = converter.to_content_evaluation(output_nn=out[i], state=st)
+            vw = state_eval.value_white
+            assert vw is not None
+            values.append(float(vw))
+
+        return values
+
+
+class _SingleEvalItem:
+    """Small adapter so we can call batch method from value_white."""
+
+    def __init__(self, state: State) -> None:
+        """Initialize the EvalItem with the given state."""
+        self._state = state
+
+    @property
+    def state(self) -> State:
+        """The state to evaluate."""
+        return self._state
+
+    @property
+    def state_representation(self) -> None:
+        """No precomputed representation."""
+        return None

anemone/node_evaluation/node_direct_evaluation/__init__.py

@@ -0,0 +1,22 @@
+"""
+This module provides functionality for evaluating nodes in a tree structure.
+
+The module includes a factory function for creating node evaluators, as well as classes for representing
+node evaluators, evaluation queries, and node evaluator arguments.
+
+Available objects:
+- AllNodeEvaluatorArgs: A named tuple representing all the arguments for creating a node evaluator.
+- NodeEvaluator: A class representing a node evaluator.
+- create_node_evaluator: A factory function for creating a node evaluator.
+- EvaluationQueries: An enumeration representing different types of evaluation queries.
+- NodeEvaluatorArgs: A class representing the arguments for creating a node evaluator.
+"""
+
+from .factory import create_node_evaluator
+from .node_direct_evaluator import EvaluationQueries, NodeDirectEvaluator
+
+__all__ = [
+    "NodeDirectEvaluator",
+    "create_node_evaluator",
+    "EvaluationQueries",
+]

anemone/node_evaluation/node_direct_evaluation/factory.py

@@ -0,0 +1,12 @@
+"""This module provides a factory function for creating node evaluators."""
+
+from valanga import State
+
+from .node_direct_evaluator import MasterStateEvaluator, NodeDirectEvaluator
+
+
+def create_node_evaluator[StateT: State = State](
+    master_state_evaluator: MasterStateEvaluator,
+) -> NodeDirectEvaluator[StateT]:
+    """Create a NodeDirectEvaluator backed by a master state evaluator."""
+    return NodeDirectEvaluator(master_state_evaluator=master_state_evaluator)

anemone/node_evaluation/node_direct_evaluation/node_direct_evaluator.py

@@ -0,0 +1,192 @@
+"""
+This module contains the implementation of the NodeEvaluator class, which is responsible for evaluating the value of
+ nodes in a tree-based move selector.
+
+The NodeEvaluator class wraps a board evaluator and a syzygy table to provide more complex evaluations of chess
+ positions. It handles queries for evaluating nodes and manages obvious over events.
+
+Classes:
+- NodeEvaluator: Wrapping node evaluator with syzygy and obvious over event.
+
+Enums:
+- NodeEvaluatorTypes: Types of node evaluators.
+
+Constants:
+- DISCOUNT: Discount factor used in the evaluation.
+
+Functions:
+- None
+
+"""
+
+from enum import Enum
+from typing import Protocol, Sequence
+
+from valanga import OverEvent, State
+from valanga.evaluations import EvalItem
+
+from anemone.nodes.algorithm_node import AlgorithmNode
+
+DISCOUNT = 0.99999999  # lokks like at the moment the use is to break ties in the evaluation (not sure if needed or helpful now)
+
+
+class NodeEvaluatorTypes(str, Enum):
+    """
+    Enum class representing different types of node evaluators.
+    """
+
+    NEURAL_NETWORK = "neural_network"
+
+
+class NodeBatchValueEvaluator(Protocol):
+    """Return value_white for each node, can use node.state_representation for speed."""
+
+    def value_white_batch_from_nodes(
+        self, nodes: Sequence[AlgorithmNode]
+    ) -> list[float]:
+        """Return value_white evaluations for a batch of nodes."""
+        ...
+
+
+class EvaluationQueries[StateT: State = State]:
+    """
+    A class that represents evaluation queries for algorithm nodes.
+
+    Attributes:
+        over_nodes (list[AlgorithmNode]): A list of algorithm nodes that are considered "over".
+        not_over_nodes (list[AlgorithmNode]): A list of algorithm nodes that are not considered "over".
+    """
+
+    over_nodes: list[AlgorithmNode[StateT]]
+    not_over_nodes: list[AlgorithmNode[StateT]]
+
+    def __init__(self) -> None:
+        """
+        Initializes a new instance of the NodeEvaluator class.
+        """
+        self.over_nodes = []
+        self.not_over_nodes = []
+
+    def clear_queries(self) -> None:
+        """
+        Clears the evaluation queries by resetting the over_nodes and not_over_nodes lists.
+        """
+        self.over_nodes = []
+        self.not_over_nodes = []
+
+
+class OverEventDetector(Protocol):
+    """Protocol for detecting over events in a game state."""
+
+    def check_obvious_over_events(
+        self, state: State
+    ) -> tuple[OverEvent | None, float | None]:
+        """Return an over event and evaluation if the state is terminal."""
+        ...
+
+
+class MasterStateEvaluator(Protocol):
+    """Protocol for evaluating the value of a state."""
+
+    over: OverEventDetector
+
+    def value_white(self, state: State) -> float:
+        """Evaluate a single state from white's perspective."""
+        ...
+
+    # the one method NodeEvaluator uses
+    def value_white_batch_items[ItemStateT: State](
+        self, items: Sequence[EvalItem[ItemStateT]]
+    ) -> list[float]:
+        """Evaluate a batch of items, defaulting to single-state calls."""
+        # default fallback: single loop, state-only
+        return [self.value_white(it.state) for it in items]
+
+
+class NodeDirectEvaluator[StateT: State = State]:
+    """
+    The NodeEvaluator class is responsible for evaluating the value of nodes in a tree structure.
+    It uses a board evaluator and a syzygy evaluator to calculate the value of the nodes.
+    """
+
+    master_state_evaluator: MasterStateEvaluator
+
+    def __init__(
+        self,
+        master_state_evaluator: MasterStateEvaluator,
+    ) -> None:
+        """
+        Initializes a NodeEvaluator object.
+
+        Args:
+            state_evaluator (MasterStateEvaluator): The state evaluator used to evaluate the chess state.
+        """
+        self.master_state_evaluator = master_state_evaluator
+
+    def check_obvious_over_events(self, node: AlgorithmNode[StateT]) -> None:
+        """
+        Updates the node.over object if the game is obviously over.
+        """
+        over_event: OverEvent | None
+        evaluation: float | None
+        over_event, evaluation = (
+            self.master_state_evaluator.over.check_obvious_over_events(node.state)
+        )
+        if over_event is not None:
+            node.tree_evaluation.over_event.becomes_over(
+                how_over=over_event.how_over,
+                who_is_winner=over_event.who_is_winner,
+                termination=over_event.termination,
+            )
+            assert evaluation is not None, (
+                "Evaluation should not be None for over nodes"
+            )
+            node.tree_evaluation.set_evaluation(evaluation=evaluation)
+
+    def evaluate_all_queried_nodes(
+        self, evaluation_queries: EvaluationQueries[StateT]
+    ) -> None:
+        """
+        Evaluates all the queried nodes.
+        """
+        # node_over: AlgorithmNode
+        # for node_over in evaluation_queries.over_nodes:
+        # assert isinstance(node_over, AlgorithmNode)
+        #    self.evaluate_over(node_over)
+
+        if evaluation_queries.not_over_nodes:
+            self.evaluate_all_not_over(evaluation_queries.not_over_nodes)
+
+        evaluation_queries.clear_queries()
+
+    def add_evaluation_query(
+        self, node: AlgorithmNode[StateT], evaluation_queries: EvaluationQueries[StateT]
+    ) -> None:
+        """
+        Adds an evaluation query for a node.
+        """
+        assert node.tree_evaluation.value_white_direct_evaluation is None
+        self.check_obvious_over_events(node)
+        if node.is_over():
+            evaluation_queries.over_nodes.append(node)
+        else:
+            evaluation_queries.not_over_nodes.append(node)
+
+    def evaluate_all_not_over(
+        self, not_over_nodes: list[AlgorithmNode[StateT]]
+    ) -> None:
+        """Evaluate all non-terminal nodes and store their evaluations."""
+        values = self.master_state_evaluator.value_white_batch_items(not_over_nodes)
+        for node, v in zip(not_over_nodes, values, strict=True):
+            node.tree_evaluation.set_evaluation(
+                self.process_evalution_not_over(v, node)
+            )
+
+    def process_evalution_not_over(
+        self, evaluation: float, node: AlgorithmNode[StateT]
+    ) -> float:
+        """
+        Processes the evaluation for a node that is not over.
+        """
+        processed_evaluation = (1 / DISCOUNT) ** node.tree_depth * evaluation
+        return processed_evaluation