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.
- 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.
- Asynchronous Behavior Trees!
This package is available on PyPI. You can install it with:
pip install GrammaticalEvolutionToolsFor pre-releases, you may need to specify the version:
pip install GrammaticalEvolutionTools==<VERSION>After installation:
import getools
from getools.worlds.grid_world import GridWorld
from getools.grammars import Grammar
...
world = GridWorld(...)This project uses Poetry 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.
# 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 poetryYou can find more detailed installation instructions for Poetry on their official website: Poetry Installation Guide
To install the core package with only its essential dependencies (for integrating it into your own projects):
# Clone the repository
git clone https://github.com/n-smith-byu/GrammaticalEvolutionTools.git
cd GrammaticalEvolutionTools
# Install the core package
poetry installIf you plan to explore the provided examples or run the Jupyter notebooks, you'll need to install the package with the examples dependency group.
# Install the package with examples dependencies
poetry install --with examplesIf you intend to modify the code, run tests, or build the documentation, install with the dev dependency group.
# Install in editable mode with dev dependencies
poetry install --with devThe 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:
# Ensure you are in the project root directory
cd examples/
jupyter lab # or jupyter notebookExamples include an implementation of the Santa Fe problem and a basic grammatical evolution algorithm.
NOTE: Incomplete
If you are developing the package, you can run the test suite using pytest. Ensure you have installed the dev dependencies.
# From the project root directory
pytestNOTE: 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:
cd docs/Then, run the appropriate command for your operating system:
For Linux / macOS / WSL:
make htmlFor Windows (Command Prompt / PowerShell):
poetry run sphinx-build -b html . _build/htmlThe 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.
This project is licensed under the MIT License.