Grammatical Evolution Tools

Table of Contents

• Introduction
• Features
  • Currently Available
  • Coming Soon
• Installation
  • PyPI
  • Local Development
    • Prerequisites
    • Core Package
    • For Notebooks and Examples
    • For Development
• Examples
• Running Tests
• Documentation
• 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

PyPI

This package is available on PyPI. You can install it with:

pip install GrammaticalEvolutionTools

For 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(...)

Local Development

Prerequisites

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 poetry

You can find more detailed installation instructions for Poetry on their official website: Poetry Installation Guide

Core Package

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 install

For 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.

# Install the package with examples dependencies
poetry install --with examples

For Development (Tests and Docs)

If 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 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:

# 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.

# 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:

cd docs/

Then, run the appropriate command for your operating system:

For Linux / macOS / WSL:

make html

For Windows (Command Prompt / PowerShell):

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.