# Neuroevolution

`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

```bash
docker compose up -d # starte neo4j db
python -m venv .venv
source .venv/bin/activate 
```
Requirements installieren:
```bash
pip install -r requirements.txt
```

## Quickstart

### CarRacing-Experiment starten

```bash
python mathema/car_racing_main.py
```
startet eine Evolutionsrunde mit Agenten in der CarRacing-Umgebung.

### Mehrere Runs (Thesis-Tests)
```bash
python mathema/eval_main.py
````
Führt mehrere unabhängige Läufe aus und aggregiert Fitness-Statistiken.