GrammaticalEvolutionTools 1.1.0a1__tar.gz

grammaticalevolutiontools-1.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nicholas Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

grammaticalevolutiontools-1.1.0a1/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: GrammaticalEvolutionTools
+Version: 1.1.0a1
+Summary: This package contains several tools for quickly setting up worlds and agents for Grammatical Evolution Projects.
+License: MIT
+License-File: LICENSE
+Author: Nick Smith
+Author-email: nicholas.smith0014@gmail.com
+Requires-Python: >=3.13,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: ipykernel (>=7.0.1,<8.0.0)
+Requires-Dist: matplotlib (>=3.10.1,<4.0.0)
+Requires-Dist: scipy (>=1.16.2,<2.0.0)
+Requires-Dist: seaborn (>=0.13.2,<0.14.0)
+Description-Content-Type: text/markdown
+
+# Grammatical Evolution Tools
+
+[![Python Version](https://img.shields.io/badge/python-3.14+-blue)](https://www.python.org/downloads/)
+[![Version](https://img.shields.io/badge/Version-1.1.0a1-blue)](https://github.com/n-smith-byu/GrammaticalEvolutionTools)
+[![GitHub License](https://img.shields.io/badge/License-MIT-green)](https://github.com/n-smith-byu/GrammaticalEvolutionTools/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-under--construction-yellow)](https://img.shields.io/badge/docs-under--construction-yellow)
+![Tests](https://img.shields.io/badge/tests-under--construction-yellow)
+
+
+---
+
+## Table of Contents
+* [Introduction](#introduction)
+* [Features](#features)
+* [Installation](#installation)
+    * [Prerequisites](#prerequisites)
+    * [Core Package](#core-package)
+    * [For Notebooks and Examples](#for-notebooks-and-examples)
+    * [For Development](#for-development)
+* [Quick Start / Usage](#quick-start--usage)
+* [Examples](#examples)
+* [Running Tests](#running-tests)
+* [Documentation](#documentation)
+* [License](#license)
+
+---
+
+## Introduction
+
+`GrammaticalEvolutionTools` is a Python package designed to simplify the setup and execution of Grammatical Evolution (GE) and other Agent-Based Modeling (ABM) projects. It provides a suite of tools for quickly spinning up worlds, defining grammars, setting up agents, and running and animating simulations. It includes a number of abstract classes you can easily inherit from and customize, with much of the underlying functionality already implemented.
+
+Whether you're building complex simulation environments or simple test cases, `getools` streamlines the boilerplate, enabling faster iteration and more effective research in grammatical evolution.
+
+*Note: This project is still in development. Code has been refactored and not all docstrings may reflect this yet.*
+
+## Features
+
+### Currently Available:
+* **World Environment Setup:** Easily define and configure custom environments for GE agents.
+* **Grammar Definition:** Inherit from common classes to create custom grammars with specific functionalities. 
+* **Agent Management:** Logic for running Agent programs and having them interact with their world. 
+* **Evolution:** Common methods for cross over and mutation, built to work with program trees.
+* **Animation:** Create customizable animations for simulations.
+
+### Coming Soon: 
+* Asynchronous Behavior Trees!
+
+## Installation
+
+Since this package is not yet published to PyPI, you will need to clone the repository and install it locally.
+
+### Prerequisites
+
+This project uses [Poetry](https://python-poetry.org/) for dependency management and packaging. Before installing the package, ensure you have Poetry installed on your system.
+
+The recommended way to install Poetry is using `pipx`, which installs Python applications in isolated environments.
+
+```bash
+# 1. Install pipx (if you don't have it)
+python -m pip install --user pipx
+python -m pipx ensurepath
+
+# 2. Install Poetry using pipx
+pipx install poetry
+```
+
+You can find more detailed installation instructions for Poetry on their official website: [Poetry Installation Guide](https://python-poetry.org/docs/#installation)
+
+
+### Core Package
+
+To install the core package with only its essential dependencies (for integrating it into your own projects):
+
+```bash
+# Clone the repository first
+git clone [https://github.com/n-smith-byu/getools.git](https://github.com/n-smith-byu/GrammaticalEvolutionTools.git)
+cd getools
+
+# Install the core package in editable mode
+poetry install
+```
+
+### To Run Notebooks and Examples
+
+If you plan to explore the provided examples or run the Jupyter notebooks, you'll need to install the package with the `examples` dependency group.
+
+```bash
+# If you haven't already, clone the repository and navigate into it
+# git clone [https://github.com/n-smith-byu/getools.git](https://github.com/n-smith-byu/GrammaticalEvolutionTools.git)
+# cd getools
+
+# Install the package with examples dependencies
+poetry install --with examples
+```
+
+### For Development
+
+If you intend to modify the code, run tests, or build the documentation, install with the `dev` dependency group.
+
+```bash
+# If you haven't already, clone the repository and navigate into it
+# git clone [https://github.com/n-smith-byu/getools.git](https://github.com/n-smith-byu/GrammaticalEvolutionTools.git)
+# cd getools
+
+# Install in editable mode with dev dependencies
+poetry install --with dev
+```
+
+---
+
+## Examples
+
+The `examples/` directory in this repository contains various Jupyter notebooks and scripts demonstrating how to use `getools` for different scenarios.
+
+To run these examples, make sure you have installed the package with the `examples` dependency group:
+
+```bash
+# Ensure you are in the project root directory
+cd examples/
+jupyter lab # or jupyter notebook
+```
+Examples include an implementation of the Santa Fe problem and a basic grammatical evolution algorithm. 
+
+---
+
+## Running Tests 
+
+*NOTE: Incomplete*
+
+If you are developing the package, you can run the test suite using `pytest`. Ensure you have installed the `dev` dependencies.
+
+```bash
+# From the project root directory
+pytest
+```
+
+---
+
+## Documentation
+
+*NOTE: Incomplete*
+
+The project's documentation is built using Sphinx. To generate the HTML documentation locally, ensure you have installed the `dev` dependencies.
+
+First, navigate to the `docs/` directory from the project root:
+
+```bash
+cd docs/
+```
+
+Then, run the appropriate command for your operating system:
+
+**For Linux / macOS / WSL:**
+```bash
+make html
+```
+
+**For Windows (Command Prompt / PowerShell):**
+```bash
+poetry run sphinx-build -b html . _build/html
+```
+
+The generated HTML documentation will be located in `docs/_build/html/index.html`. You can open this file in your web browser to view the documentation.
+
+---
+
+## License
+
+This project is licensed under the [MIT License](https://github.com/n-smith-byu/GrammaticalEvolutionTools/blob/main/LICENSE).
+
+
+---
+

grammaticalevolutiontools-1.1.0a1/README.md

@@ -0,0 +1,172 @@
+# Grammatical Evolution Tools
+
+[![Python Version](https://img.shields.io/badge/python-3.14+-blue)](https://www.python.org/downloads/)
+[![Version](https://img.shields.io/badge/Version-1.1.0a1-blue)](https://github.com/n-smith-byu/GrammaticalEvolutionTools)
+[![GitHub License](https://img.shields.io/badge/License-MIT-green)](https://github.com/n-smith-byu/GrammaticalEvolutionTools/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-under--construction-yellow)](https://img.shields.io/badge/docs-under--construction-yellow)
+![Tests](https://img.shields.io/badge/tests-under--construction-yellow)
+
+
+---
+
+## Table of Contents
+* [Introduction](#introduction)
+* [Features](#features)
+* [Installation](#installation)
+    * [Prerequisites](#prerequisites)
+    * [Core Package](#core-package)
+    * [For Notebooks and Examples](#for-notebooks-and-examples)
+    * [For Development](#for-development)
+* [Quick Start / Usage](#quick-start--usage)
+* [Examples](#examples)
+* [Running Tests](#running-tests)
+* [Documentation](#documentation)
+* [License](#license)
+
+---
+
+## Introduction
+
+`GrammaticalEvolutionTools` is a Python package designed to simplify the setup and execution of Grammatical Evolution (GE) and other Agent-Based Modeling (ABM) projects. It provides a suite of tools for quickly spinning up worlds, defining grammars, setting up agents, and running and animating simulations. It includes a number of abstract classes you can easily inherit from and customize, with much of the underlying functionality already implemented.
+
+Whether you're building complex simulation environments or simple test cases, `getools` streamlines the boilerplate, enabling faster iteration and more effective research in grammatical evolution.
+
+*Note: This project is still in development. Code has been refactored and not all docstrings may reflect this yet.*
+
+## Features
+
+### Currently Available:
+* **World Environment Setup:** Easily define and configure custom environments for GE agents.
+* **Grammar Definition:** Inherit from common classes to create custom grammars with specific functionalities. 
+* **Agent Management:** Logic for running Agent programs and having them interact with their world. 
+* **Evolution:** Common methods for cross over and mutation, built to work with program trees.
+* **Animation:** Create customizable animations for simulations.
+
+### Coming Soon: 
+* Asynchronous Behavior Trees!
+
+## Installation
+
+Since this package is not yet published to PyPI, you will need to clone the repository and install it locally.
+
+### Prerequisites
+
+This project uses [Poetry](https://python-poetry.org/) for dependency management and packaging. Before installing the package, ensure you have Poetry installed on your system.
+
+The recommended way to install Poetry is using `pipx`, which installs Python applications in isolated environments.
+
+```bash
+# 1. Install pipx (if you don't have it)
+python -m pip install --user pipx
+python -m pipx ensurepath
+
+# 2. Install Poetry using pipx
+pipx install poetry
+```
+
+You can find more detailed installation instructions for Poetry on their official website: [Poetry Installation Guide](https://python-poetry.org/docs/#installation)
+
+
+### Core Package
+
+To install the core package with only its essential dependencies (for integrating it into your own projects):
+
+```bash
+# Clone the repository first
+git clone [https://github.com/n-smith-byu/getools.git](https://github.com/n-smith-byu/GrammaticalEvolutionTools.git)
+cd getools
+
+# Install the core package in editable mode
+poetry install
+```
+
+### To Run Notebooks and Examples
+
+If you plan to explore the provided examples or run the Jupyter notebooks, you'll need to install the package with the `examples` dependency group.
+
+```bash
+# If you haven't already, clone the repository and navigate into it
+# git clone [https://github.com/n-smith-byu/getools.git](https://github.com/n-smith-byu/GrammaticalEvolutionTools.git)
+# cd getools
+
+# Install the package with examples dependencies
+poetry install --with examples
+```
+
+### For Development
+
+If you intend to modify the code, run tests, or build the documentation, install with the `dev` dependency group.
+
+```bash
+# If you haven't already, clone the repository and navigate into it
+# git clone [https://github.com/n-smith-byu/getools.git](https://github.com/n-smith-byu/GrammaticalEvolutionTools.git)
+# cd getools
+
+# Install in editable mode with dev dependencies
+poetry install --with dev
+```
+
+---
+
+## Examples
+
+The `examples/` directory in this repository contains various Jupyter notebooks and scripts demonstrating how to use `getools` for different scenarios.
+
+To run these examples, make sure you have installed the package with the `examples` dependency group:
+
+```bash
+# Ensure you are in the project root directory
+cd examples/
+jupyter lab # or jupyter notebook
+```
+Examples include an implementation of the Santa Fe problem and a basic grammatical evolution algorithm. 
+
+---
+
+## Running Tests 
+
+*NOTE: Incomplete*
+
+If you are developing the package, you can run the test suite using `pytest`. Ensure you have installed the `dev` dependencies.
+
+```bash
+# From the project root directory
+pytest
+```
+
+---
+
+## Documentation
+
+*NOTE: Incomplete*
+
+The project's documentation is built using Sphinx. To generate the HTML documentation locally, ensure you have installed the `dev` dependencies.
+
+First, navigate to the `docs/` directory from the project root:
+
+```bash
+cd docs/
+```
+
+Then, run the appropriate command for your operating system:
+
+**For Linux / macOS / WSL:**
+```bash
+make html
+```
+
+**For Windows (Command Prompt / PowerShell):**
+```bash
+poetry run sphinx-build -b html . _build/html
+```
+
+The generated HTML documentation will be located in `docs/_build/html/index.html`. You can open this file in your web browser to view the documentation.
+
+---
+
+## License
+
+This project is licensed under the [MIT License](https://github.com/n-smith-byu/GrammaticalEvolutionTools/blob/main/LICENSE).
+
+
+---

grammaticalevolutiontools-1.1.0a1/pyproject.toml

@@ -0,0 +1,42 @@
+[tool.poetry]
+name = "GrammaticalEvolutionTools"
+version = "1.1.0a1"
+description = "This package contains several tools for quickly setting up worlds and agents for Grammatical Evolution Projects."
+authors = ["Nick Smith <nicholas.smith0014@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+packages = [
+    { include = "getools", from = "src" }
+]
+
+[tool.poetry.dependencies]
+python = ">=3.13,<4.0"
+matplotlib = ">=3.10.1,<4.0.0"
+seaborn = ">=0.13.2,<0.14.0"
+ipykernel = "^7.0.1"
+scipy = "^1.16.2"
+
+[tool.poetry.group.dev]
+optional = true
+
+[tool.poetry.group.dev.dependencies]
+sphinx-rtd-theme = "^3.0.2"
+numpydoc = "^1.9.0"
+pytest-mock = "^3.14.1"
+sphinx = "^9.0.4"
+pytest = "^9.0.2"
+
+[tool.poetry.group.examples]
+optional = true
+
+[tool.poetry.group.examples.dependencies]
+notebook = "^7.4.4"
+tqdm = "^4.67.1"
+ipympl = "^0.9.8"
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

grammaticalevolutiontools-1.1.0a1/src/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__ = []

grammaticalevolutiontools-1.1.0a1/src/getools/agents/__init__.py

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

grammaticalevolutiontools-1.1.0a1/src/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