NEATtactics

📋 Table of contents

• NEATtactics
  • Watch Mario Clear the First Level
  • Description
    • Prerequisites
  • Getting started
    • Note on venv
  • Usage
    • Basic Command
    • Example Commands
    • Command Descriptions
      • Train
      • Test
      • Graph
      • Play
  • Testing
    • Test execution environment
  • 📚 Documentation
  • Team
    • License

Watch Mario Clear the First Level

Description

NEATtactics is a project that aims to implement the NEAT (NeuroEvolution of Augmenting Topologies) algorithm to train a neural network to play a classic platformer game inspired by Super Mario. The idea is to evolve a neural network using NEAT, allowing an AI agent to learn and improve its gameplay strategies over time, starting from scratch and evolving through generations.

Our project takes inspiration from SethBling's MarI/O video, where he demonstrates a neural network learning to play Super Mario World using the NEAT algorithm. You can watch SethBling video here and Chrispresso video here to get a better understanding of the principles behind our approach.

To implement this, we are basing our work on the research paper "Evolving Neural Networks through Augmenting Topologies" by Kenneth O. Stanley and Risto Miikkulainen. This paper introduces the NEAT algorithm, which evolves neural network topologies along with weights to create more efficient and sophisticated solutions.

In this project, we will:

• Implement the NEAT algorithm from scratch, following the guidelines from the original research paper.
• Use a simulation environment based on a classic Super Mario platformer where our AI agent will learn to navigate and play the game.
• Continuously evolve the agent's neural network to enhance its performance, aiming for progressively better gameplay as it learns from experience.

Join us in exploring the fascinating world of neuroevolution and AI-driven gameplay!

Prerequisites

• Ensure that git is installed on your machine. Download Git
• Ensure that you are using python version==3.8.x. Download Python

Getting started

Start off by cloning the repository to your local machine.

git clone https://github.com/CogitoNTNU/NEATactics

Next, navigate to the project directory:

cd NEATtactics

Create a virtual environment to manage the project dependencies:

python -m venv venv

Activate the virtual environment on Mac/Linux:

source venv/bin/activate

Alternatively use this command on windows:

venv\Scripts\activate

Install the project dependencies:

pip install -r requirements.txt

Now you are ready to run the project!

Note on venv

You will need to activate the virtual environment for each new shell session. If you want to deactivate the virtual environment, you can do so by either closing the terminal or running the following command:

deactivate

Usage

The project can be run from the command line using the main.py script. The script supports several commands, including training and testing genomes, visualizing fitness data, and playing a trained genome.

Basic Command

python main.py <command> [options]

Example Commands

• Train genomes:

python main.py train --neat_name my_saved_neat --extra_number 100

• Test genomes:

python main.py test 0 10

• Graph fitness data:

python main.py graph

Play the best genome:

python main.py play --best

Command Descriptions

Train

The train command initializes and trains genomes using the NEAT algorithm. It supports the following options:

• --neat_name: The name of a previously trained NEAT object located in the trained_population directory (default: empty string).
• extra_number: An optional parameter specifying the number of generations for training (default: 0). If not specified, the configuration’s default number of generations will be used.

Example:

python main.py train --neat_name my_neat_population --extra_number 50

Test

The test command tests a range of genomes in the environment. The command accepts:

• from_gen: The starting generation number.
• to_gen: The ending generation number (inclusive).

Example:

python main.py test 0 5

This will test genomes from generation 0 up to generation 5.

Graph

The graph command visualizes the fitness data accumulated during training. When executed, it reads the fitness data from the data/fitness/fitness_values.txt file and plots the best, average, and minimum fitness values for each generation. The generated plot is saved as fitness_plot.png in the data/fitness directory.

• The fitness values are extracted from fitness_values.txt using the read_fitness_file function.
• A line graph is generated where:
  • The x-axis represents generations.
  • The y-axis represents fitness values (Best, Average, Min).
• The plot is displayed and saved automatically.

Example:

python main.py graph

Ensure that fitness_values.txt exists in the data/fitness directory before running this command, as it is the source file for generating the graph.

Play

The play command runs the environment using the best genome from the most recent training session. It has two optional arguments:

-g or --generation: Specifies the generation of the genome you want to play. If not provided, the latest genome will be used. -b or --best: This flag indicates that the best genome from the specified generation (or the latest generation if -g is not provided) should be played.

Examples:

• To play the best genome from the latest generation:

python main.py play --best

• To play the genome from a specific generation (e.g., generation 10):

python main.py play --generation 10

• To play the best genome from generation 10:

python main.py play --generation 10 --best

This flexibility allows you to test and visualize the performance of genomes from different stages of evolution.

Testing

To run the test suite, run the following command from the root directory of the project:

pytest

To get a detailed report of the test coverage, run the following commands:

coverage run --source=src -m pytest
coverage html

Next, open the htmlcov/index.html file in your browser to view the detailed coverage report. In linux and Mac, you can use the following command:

open htmlcov/index.html

You might want to clean up the coverage files before running the tests again. To do this, run the following commands:

coverage erase
rm -rf htmlcov

Test execution environment

When first installing the project, it is advised to run the following tests:

pytest -m "environment"

Which will check for CUDA compatibility and the current OS. Specifically, if you are running on Windows, you might have troubles installing the gym_super_mario_bros package.

📚 Documentation

• 🛠️ Developer setup
• 🎤 Final presentation
• 📄 Research paper: Efficient Evolution of Neural Network Topologies
• 📄 Research paper: Evolving Neural Networks through Augmenting Topologies

Team

This project would not have been possible without the hard work and dedication of all of the contributors. Thank you for the time and effort you have put into making this project a reality.

Christian Fredrik

Brage

Kristian

Ludvig

Kacper

Vetle

Håkon

License

---

Distributed under the MIT License. See LICENSE for more information.