GrammaticalEvolutionTools 1.1.0a1__py3-none-any.whl

getools/__init__.py

@@ -0,0 +1,6 @@
+from .meta import BaseNode, BaseNodeMeta, InheritingNodeMeta, WorldAnimation
+from .worlds.base import World
+from .agents import Agent, AgentProgramTree
+
+
+__all__ = []

getools/agents/__init__.py

@@ -0,0 +1,4 @@
+from .agent import Agent
+from .agent_program import AgentProgramTree
+
+__all__ = ['Agent', 'AgentProgramTree']

getools/agents/agent.py

@@ -0,0 +1,212 @@
+from .agent_program import AgentProgramTree
+from ..grammars import Grammar
+
+from numbers import Number
+from uuid import uuid4
+
+from typing import Type, TYPE_CHECKING
+import warnings
+
+if TYPE_CHECKING:
+    from ..worlds import World
+
+class Agent:
+
+    @classmethod
+    def default_grammar(cls) -> Grammar:
+        return cls._default_grammar
+    
+    @classmethod
+    def default_program_cls(cls) -> Type[AgentProgramTree]:
+        mangled = f"_{cls.__name__}__default_program_cls"
+        
+        if not hasattr(cls, mangled):
+            default_grammar = cls.default_grammar()
+            if default_grammar:
+                class AgentProgram(AgentProgramTree):
+                    _grammar = default_grammar
+                    pass
+                setattr(cls, mangled, AgentProgram)
+        
+        return getattr(cls, mangled, None)
+    
+    _default_grammar = None
+    _requires_world = False
+
+    # - - Exceptions - - 
+
+    class WorldNotSetError(RuntimeError):
+        pass
+
+    class AlreadyInWorldError(RuntimeError):
+        pass
+
+    class AssignedProgramError(RuntimeError):
+        pass
+
+    class NotAssignedProgramError(RuntimeError):
+        pass
+
+    # - - Initialization - -
+
+    def __init__(self, program: AgentProgramTree = None, autogen=True):
+        self._world: World = None
+        self._program: AgentProgramTree = None
+        self._uuid = uuid4()       # just to make hashable
+
+        self._score = 0
+        self._num_actions = 0
+
+        if program:
+            self._assert_valid_program(program)
+            self._set_program(program)
+        elif autogen:
+            program_cls = self.default_program_cls()
+            if not program_cls:
+                warnings.warn(
+                        "`autogen` set to True, but no default " \
+                        "grammar found for " \
+                        f"{type(self).__name__}. Could not create a program.",
+                        UserWarning
+                        )
+            else:
+                self._set_program(program_cls())
+        
+    # - - Assertions - -
+
+    def _assert_not_in_world(self):
+        if self.assigned_to_world():
+            raise Agent.AlreadyInWorldError(
+                "Cannot add agent to world because agent is already in another world. "
+                "Remove agent from that world first. "
+                )
+        
+    def _assert_not_assigned_program(self):
+        if self._program:
+            raise Agent.AssignedProgramError(
+                "Cannot set program when agent is already assigned a program. "
+                "Please remove old program first."
+            )
+        
+    def _assert_valid_program(self, program):
+        if not isinstance(program, AgentProgramTree):
+            raise TypeError('program must be an instance of AgentProgramTree.')
+        if program.agent and program.agent is not self:
+            raise ValueError(
+                "Cannot bind program to this agent when program is already "
+                "bound to another agent. Unbind the program first."
+                )
+        
+    # - - World Internal Access - -
+
+    def _set_world(self, world: 'World'):
+        self._assert_not_in_world()
+
+        self._world = world
+
+    def _clear_world(self):
+        self._world = None
+
+    # - - Helpers - - 
+
+    def _set_program(self, program: AgentProgramTree):
+        self._program = program
+        if program: 
+            program._set_agent(self)
+
+    def _remove_program(self) -> AgentProgramTree:
+        program = self._program
+        program._set_agent(None)
+        self._program = None
+        
+        return program
+    
+    def _replace_program(self, new_program: AgentProgramTree) -> AgentProgramTree:
+        old = self._remove_program()
+        try:
+            self._set_program(new_program)
+        except (TypeError, ValueError) as e:
+            self._set_program(old)
+            raise e
+
+        return old
+    
+    # - - Public - - 
+
+    def reset(self, program: AgentProgramTree = None):
+        if program:
+            self._assert_valid_program(program)
+            self._replace_program(program)
+
+        if self._program and self._program.running():
+            self._program.kill()
+        
+        self._num_actions = 0
+        self._score = 0
+
+    def copy_program(self):
+        return self._program.copy()
+
+    # - - Running Program - -
+
+    def execute_program(self, n=1):
+        """
+        Resets the program and runs to completion once.
+        """
+        if self._program.running():
+            self._program.kill()
+
+        self._program.run(n=n)
+
+    def tick(self, loop: bool=True):
+        """
+            Runs the program through the next executable node. Exits if run and no nodes are left. 
+            If loop is True (default), then the program will restart rather than exiting. 
+        """
+        if self._requires_world and not self.assigned_to_world():
+            raise Agent.WorldNotSetError("Cannot run program without agent being assigned a world unless this is a worldless agent.")
+
+        status = self._program.tick()
+        if status == AgentProgramTree.Status.EXITED and loop:
+            self._program.tick()
+
+    def give_reward(self, amount):
+        self._score += amount
+
+    # - - Listeners - -
+
+    def _on_action_taken(self):
+        self._record_action()
+
+    # - - Operations - - 
+
+    def _record_action(self):
+        self._num_actions += 1
+
+    # - - Getters - -
+
+    def assigned_to_world(self):
+        return self._world is not None
+    
+    @property
+    def program(self) -> AgentProgramTree:
+        return self._program
+    
+    @property
+    def score(self) -> Number:
+        return self._score
+    
+    @property
+    def num_actions(self) -> int:
+        return self._num_actions
+    
+    # - - Other Methods - -
+    
+    def __hash__(self):
+        return hash(self._uuid)
+    
+    def __lt__(self, other):
+        if not isinstance(other, Agent):
+            raise TypeError("Cannot compare Agent to non-Agent")
+        
+        return self.score < other.score

getools/agents/agent_program.py

@@ -0,0 +1,105 @@
+from ..programs.base.program_tree import ProgramTree
+from ..programs.mods.grammar import GrammarProgramAddin
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..agents import Agent
+
+
+class AgentProgramTree(ProgramTree, GrammarProgramAddin):
+    
+    @classmethod
+    def _assert_agent_valid(cls, agent):
+        grammar = cls.get_grammar()
+        if not isinstance(agent, grammar.target_agent_type):
+            raise TypeError(
+                "Cannot bind tree to an agent with which " \
+                "it is not compatible"
+                )
+    
+    # - - Exceptions - - 
+
+    class MissingAgentError(RuntimeError):
+        """Exception raised when attempting to run a program not attached to an an agent."""
+        pass
+
+    class BoundToAgentError(RuntimeError):
+        """Exception raised for attempted operations requiring the program to be unbound from an agent when it is not."""
+        pass
+
+    # - - Local Assertions - - 
+        
+    def _assert_editable(self):
+        if self.bound_to_agent():
+            raise AgentProgramTree.BoundToAgentError(
+                "Cannot modify a program while it is bound to an agent. "
+                "Please remove the program from the agent first or create "
+                "a copy to modify. "
+            )
+        ProgramTree._assert_editable(self)
+        
+    def _assert_runnable(self):
+        if not self.bound_to_agent():
+            raise AgentProgramTree.MissingAgentError(
+                "Cannot run program when it is not bound to an agent."
+            )
+        ProgramTree._assert_runnable(self)
+
+    # - - Initialization - - 
+
+    def __init__(self, root=None, autofill=True):
+        self._agent = None
+        ProgramTree.__init__(self, root, autofill=autofill)
+        
+    def _verify_and_set_root(self, root):
+        GrammarProgramAddin._verify_and_set_root(self, root)
+
+    # - - Agent Access - - 
+    
+    def _set_agent(self, agent):
+        """Sets the agent instance to which this program is bound.
+
+        This method should typically only be called by an instance of
+        :py:class:`~.agents.Agent` itself to establish the binding.
+
+        Parameters
+        ----------
+        agent : Agent
+            The agent instance to bind the program to.
+        """
+        self._assert_agent_valid(agent)
+        self._agent = agent
+    
+    # - - Public Methods
+
+    def bound_to_agent(self) -> bool:
+        """Checks if the program is currently bound to an agent.
+
+        Returns
+        -------
+        bool
+            :py:obj:`True` if an :py:class:`~.agents.Agent` instance is attached to the program
+            (:py:attr:`~.ProgramTree._agent` is not :py:obj:`None`), :py:obj:`False` otherwise.
+        """
+        return self._agent is not None
+        
+    def is_editable(self):
+        return ProgramTree.is_editable(self) and \
+                not self.bound_to_agent()
+    
+    def is_runnable(self):
+        return ProgramTree.is_runnable() and \
+                self.bound_to_agent()
+    
+    @property
+    def agent(self) -> 'Agent':
+        """The agent instance to which this program is currently attached.
+
+        Returns
+        -------
+        Agent or None
+            The attached :py:class:`~.agents.Agent` instance, or :py:obj:`None`
+            if no agent is currently bound.
+        """
+        return self._agent

getools/evolution/__init__.py

@@ -0,0 +1,10 @@
+from .cross_over import pick_compatible_nodes_same_type_only, \
+    pick_compatible_nodes_any_valid_replacement, \
+    cross_over_programs
+from .mutation import mutate_terminals, replace_random_branch
+
+
+__all__ = ['pick_compatible_nodes_same_type_only', 
+           'pick_compatible_nodes_any_valid_replacement',
+           'cross_over_programs', 'mutate_terminals', 
+           'replace_random_branch']

getools/evolution/cross_over.py

@@ -0,0 +1,110 @@
+from ..programs.nodes.basic_nodes import TerminalNode
+from ..programs import ProgramTree, ProgramNode
+import random
+
+from typing import Literal, Type, Tuple
+
+
+CrossOverOption = Literal['same', 'any']
+
+def pick_compatible_nodes_same_type_only(
+    program1: ProgramTree, program2: ProgramTree, 
+    exclude: list[Type[ProgramNode]] = None, 
+    exclude_children_of_roots: bool = False
+    ) -> Tuple[ProgramNode, ProgramNode]:
+    
+    incompatible_types = tuple(exclude or [])
+    
+    # Get all eligible node types from program1 (excluding root and incompatible types)
+    eligible_types = set()
+    possible_node1s = []
+    
+    for node_type in program1.types_iter():
+        if not issubclass(node_type, incompatible_types) \
+            and node_type in program2.node_types:
+            eligible_types.add(node_type)
+            possible_node1s.extend(program1.get_nodes_by_type(node_type))
+    
+    # if no matching types, return None, None
+    if not eligible_types:
+        return None, None
+    
+    # attempt to pick a matching type
+    nodes_picked = False
+
+    while not nodes_picked:
+        possible_node1s = [node for node in possible_node1s \
+                           if type(node) in eligible_types \
+                              and node is not program1._root]
+        
+        if not possible_node1s:
+            return None, None
+    
+        # choose a random node from program1
+        node1: ProgramNode = random.choice(possible_node1s)
+        node1_child_of_root = node1._parent is program1.root
+
+        # get a possible list of nodes from program2
+        possible_node2s = [node for node in program2.node_iter(type=type(node1)) \
+                           if type(node) == type(node1) \
+                            and node is not program2._root \
+                            and (not exclude_children_of_roots \
+                                 or not node1_child_of_root \
+                                 or node._parent is not program2.root) \
+                            ]
+        
+        # if no matches, remove the type and try again
+        if not possible_node2s:
+            eligible_types.remove(type(node1))
+            continue
+
+        # once a compatible type is found, choose node2
+        node2 = random.choice(possible_node2s)
+        
+        nodes_picked = True
+
+    return node1, node2
+
+
+def pick_compatible_nodes_any_valid_replacement(program1: ProgramTree, program2: ProgramTree) -> Tuple[ProgramNode, ProgramNode]:
+    """Not Implemented"""
+    # TODO: Implement this function
+    picked = False
+    incompatible_types = set([TerminalNode])
+    possible_node1s = []
+    while not picked:
+        possible_node1s = [node for node in (possible_node1s or program1.node_iter()) \
+                           if not isinstance(node, tuple(incompatible_types))]
+        node1: ProgramNode = random.choice(possible_node1s)
+    
+    return NotImplemented
+
+
+def cross_over_programs(program1: ProgramTree, program2: ProgramTree, 
+               cross_over_option: CrossOverOption = 'same') -> list[ProgramTree]:
+
+    # copy the nodes as to not modify the originals
+    program1 = program1.copy()
+    program2 = program2.copy()
+
+    # select a pair of compatible nodes.
+    # excludes terminals and prevents children of root nodes 
+    # from being swapped with each other (root nodes excluded automatically)
+    if cross_over_option == 'same':
+        node1, node2 = pick_compatible_nodes_same_type_only(
+            program1, program2, exclude=[TerminalNode],
+            exclude_children_of_roots=True
+        )
+    elif cross_over_option == 'any':
+        raise NotImplementedError("The 'any' option is currently under development.")
+        # pick_compatible_nodes_any_valid_replacement(program1, program2)
+    
+    if not node1 or not node2:      # if no match was found
+        return []
+
+    # swap the nodes in each tree
+    program1.replace_node(node1, node2.copy())
+    program2.replace_node(node2, node1)
+
+    # return a list of the newly created nodes
+    return [program1, program2]

getools/evolution/mutation.py

@@ -0,0 +1,21 @@
+from ..programs import ProgramTree
+import random
+
+def mutate_terminals(program:ProgramTree, num_mutations, terminal_types:list[type]):
+    possible_nodes = [node for node in program.nodes if type(node) \
+                        in terminal_types]
+    
+    num_mutations = min(num_mutations, len(possible_nodes))
+    for k in range(num_mutations):
+        node = random.choice(possible_nodes)
+        if node in program.nodes:
+            program.replace_node(node)
+            possible_nodes.remove(node)
+        else:
+            print('error')
+
+def replace_random_branch(program: ProgramTree, possible_node_types:list[type]):
+    possible_nodes = [n for n in program.nodes if type(n) in possible_node_types]
+    node = random.choice(possible_nodes)
+    program.replace_node(node)          # randomly replaces node by default
+

getools/grammars/__init__.py

@@ -0,0 +1,5 @@
+from .grammar import Grammar
+from .grammar_node import GrammarNode, OutOfContextError
+from ..programs.mods.grammar.node_converter import as_grammar_node
+
+__all__ = ['Grammar', 'GrammarNode', 'OutOfContextError', 'as_grammar_node']

getools/grammars/grammar.py

@@ -0,0 +1,140 @@
+from .grammar_node import GrammarNode
+
+from typing import Type, TYPE_CHECKING
+import warnings
+
+if TYPE_CHECKING:
+    from ..agents import Agent
+
+class Grammar:
+
+    class MultipleRootsException(ValueError):
+        def __init__(self):
+            super(Grammar.MultipleRootsException, self).__init__("Multiple Root Nodes Defined within Grammar.")
+
+    class NoRootDefinedException(ValueError):
+        def __init__(self):
+            super(Grammar.NoRootDefinedException, self).__init__("No Root Nodes Defined within Grammar.")
+
+    current_grammar = None
+
+    def __init__(self, target_agent_type: 'Type[Agent]' = None, 
+                 warnings=True):
+        self._roots: list[Type[GrammarNode]] = []
+        self._all_node_classes: dict[str, Type[GrammarNode]] = {}
+        self._concrete_types: set[Type[GrammarNode]] = set()
+        self._abstract_types: set[Type[GrammarNode]] = set()
+
+        self._target_agent_type = target_agent_type
+        self._warnings = warnings
+        self._is_valid = False
+
+    def __enter__(self):
+        Grammar.current_grammar = self
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        Grammar.current_grammar = None
+
+        if exc_type is None:
+            self._validate()
+            self._is_valid = True
+        
+        return self._is_valid
+
+    def _validate(self):
+        if len(self._roots) == 0:
+            raise Grammar.NoRootDefinedException()
+        elif len(self._roots) > 1:
+            raise Grammar.MultipleRootsException()
+        
+        for cls in self._abstract_types.union(self._concrete_types):
+            self._all_node_classes[cls.__name__] = cls
+
+        # Make sure all possible children are also in the Grammar
+        seen_nodes = set()
+        for node_cls in self._all_node_classes.values():
+            try:
+                node_cls._resolve_possible_children()
+                
+            except KeyError as e:
+                raise LookupError(f"Error resolving possible children for {node_cls.__name__}. " + \
+                                   "Child not defined within the scope of the Grammar.") from e
+            
+            for chld_cls in node_cls._ALL_POSSIBLE_CHILDREN:
+                
+                error = None
+                if chld_cls is self.root:
+                    error = "Root node class"
+                if chld_cls in self._abstract_types:
+                    error = "Abstract node class"
+                if error is not None:
+                    raise ValueError(f"{error} cannot be listed as a possible child of another class. Class at fault: {node_cls.__name__} referencing {chld_cls.__name__}")
+                    
+                seen_nodes.update(node_cls._ALL_POSSIBLE_CHILDREN)
+
+        if self._warnings:
+            # Raise a warning if abstract classes exist that weren't used to make concrete classes
+            for abstract_class in self._abstract_types:
+                implemented = False
+                for cls in self._concrete_types:
+                    if issubclass(cls, abstract_class):
+                        implemented = True
+                        break
+                if not implemented:
+                    warnings.warn(f"Abstract class {abstract_class.__name__} was defined but no concrete classes were ever created from it. " + 
+                                "Please note that all concrete classes must have no parameters other than self in their __init__ function, " + \
+                                "otherwise they will still be considered abstract classes.", 
+                                UserWarning)
+
+            # Raise a warning if a concrete class (besides the root) is not a possible child of any other class
+            for node_cls in self._concrete_types:
+                if node_cls is self.root:
+                    continue
+
+                if node_cls not in seen_nodes:
+                    warnings.warn(f"{node_cls.__name__} is not listed as a possible child type for any other node in its grammar.", 
+                                UserWarning)
+                
+
+    # --------------------
+
+    def register(self, cls: Type[GrammarNode]):
+        """Register a node class inside the grammar."""
+
+        cls._GRAMMAR = self
+
+        if cls.is_abstract_class():
+            self._abstract_types.add(cls)
+        else:
+            if cls._IS_ROOT:
+                self._roots.append(cls)
+
+            self._concrete_types.add(cls)
+                
+    def get_class(self, cls_name: str) -> Type[GrammarNode]:
+        return self._all_node_classes[cls_name]
+
+    @property
+    def is_valid(self) -> bool:
+        return self._is_valid
+
+    @property
+    def root(self) -> Type[GrammarNode]:
+        return self._roots[0]
+    
+    @property
+    def warnings_enabled(self) -> bool:
+        return self._warnings
+    
+    @property
+    def abstract_classes(self) -> set[Type[GrammarNode]]:
+        return self._abstract_types.copy()
+
+    @property
+    def valid_node_classes(self) -> set[Type[GrammarNode]]:
+        return self._concrete_types.copy()   
+    
+    @property
+    def target_agent_type(self) -> 'Type[Agent]':
+        return self._target_agent_type