mathema ist ein experimentelles Neuroevolutions-Framework in Python, das agentenbasierte Architekturen mit evolutiven Mechanismen kombiniert und sich dabei architektonisch am DXNN-System von Gene Sher orientiert. Das Projekt ist modular aufgebaut und erlaubt die Evaluation evolvierender Agenten in verschiedenen Scapes (einer angepassten CarRacing-Umgebung).

Der Fokus liegt auf:

evolutionären Lernprozessen
populationsbasierten Trainingsläufen
reproduzierbarer Evaluation
klarer Trennung von Genotyp, Phänotyp und Umgebung

Projektüberblick

Das Framework besteht aus mehreren logisch getrennten Komponenten:

core/
Zentrale Evolutionslogik (Agenten, Genotypen, Mutationen, Selektion, Populationen)
scape/
Umgebungen, in denen Agenten agieren (z. B. CarRacing)
eval / main-Skripte
Training, Evaluation, Vergleich mehrerer Runs
utils/
Hilfsfunktionen (Logging, Konfiguration, Seed-Handling, I/O)
archive/
Ältere oder experimentelle Implementationen (nicht aktiv genutzt)

Verzeichnisstruktur

mathema/ ├── core/ # Evolutionskern (Agent, Genotyp, Population, Mutation) ├── scape/ # Umgebungen / Aufgabenräume ├── utils/ # Hilfsfunktionen ├── archive/ # Alte / experimentelle Module ├── eval_main.py # Evaluations- & Benchmark-Skript ├── car_racing_main.py # Einstiegspunkt für CarRacing-Experimente

Zentrale Konzepte

Agent

Ein Agent repräsentiert eine evolvierbare Einheit, die:

einen Genotyp besitzt
daraus einen Phänotyp (z. B. neuronales Netz) ableitet
in einer Scape Aktionen ausführt

Genotyp / Phänotyp

Der Genotyp beschreibt die Struktur (z. B. Neuronen, Kanten, Parameter)
Der Phänotyp ist die ausführbare Repräsentation (z. B. Policy / Controller)

Neuroevolution

Populationen mehrerer Agenten
Mutation (Topologie & Parameter)
Selektion auf Basis von Fitness
optional populationsbasierte Strategien

Scapes

Eine Scape definiert:

Zustandsraum
Aktionsraum
Reward-/Fitness-Berechnung
Episodenlogik

Installation

Virtuelle Umgebung und Neo4j DB

docker compose up -d # starte neo4j db
python -m venv .venv
source .venv/bin/activate

Requirements installieren:

pip install -r requirements.txt

Quickstart

CarRacing-Experiment starten

python mathema/car_racing_main.py

startet eine Evolutionsrunde mit Agenten in der CarRacing-Umgebung.

Mehrere Runs (Thesis-Tests)

python mathema/eval_main.py

Führt mehrere unabhängige Läufe aus und aggregiert Fitness-Statistiken.