NEATtactics

📋 Table of contents

• NEATtactics
  • Watch Mario Clear the First Level
  • Description
    • Prerequisites
  • Getting started
  • Usage
    • Basic Command
    • Example Commands
    • Command Descriptions
      • Train
      • 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 have uv installed install uv

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

Use uv to create a virtual environment with all required dependencies:

uv sync

Now you are ready to run the project!

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

uv run main.py <command> [options]

Example Commands

• Train genomes:

uv run main.py --neat_name my_saved_neat train --n_generations 100

• Graph fitness data:

uv run main.py --neat_name my_saved_neat graph

Play the best genome:

uv run main.py --neat_name my_saved_neat play

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).
• --n_generations: 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:

uv run main.py --neat_name my_neat_population train --n_generations 50

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:

uv run 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:

uv run main.py play

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

uv run main.py play -f 10 -t 10

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:

uv run pytest

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

uv run coverage run --source=src -m pytest
uv run 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:

uv run coverage erase
rm -rf htmlcov

Test execution environment

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

uv run 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.