SNN Engine with Neurotransmitter

Simulierte neuronale Netze (Spiking Neural Networks) mit einem chemisch-hormonellen Modulationssystem.

Projektstand: Dezember 2025 · Sprache: Python · Kern: PyTorch (GPU/CPU)

---

⚠️ Wichtige Hinweise (bitte zuerst lesen)

1. Herkunft des Codes. Der Code in diesem Repository wurde menschlich geschrieben. Nur einzelne Teilstellen wurden dabei mit KI-Unterstützung erzeugt oder geprüft. Es handelt sich also nicht um ein rein KI-generiertes Projekt.

2. Herkunft dieser README. Diese README.md ist vollständig KI-generiert. Sie dient ausschließlich der Dokumentation und der Einordnung des Codes – sie ist keine Originalquelle des Autors.

3. Reifegrad: erster Entwurf / Proof of Concept. Der Code ist bewusst als erster Entwurf und Proof of Concept (PoC) zu verstehen. Er ist an vielen Stellen noch nicht optimiert, enthält experimentelle Parameter, TODOs und vereinfachte Annahmen. Er sollte nirgends für produktive, wissenschaftlich belastbare oder sicherheitskritische Zwecke eingesetzt werden – weder als Entscheidungsgrundlage noch als Referenzimplementierung.

4. Visualisierungs-Skripte. Die Dateien generate_readme_graphics.py (PNG-Grafiken) und generate_animation_graphics.py (GIF-Animationen) wurden vollständig KI-generiert und dienen ausschließlich der Visualisierung für diese README. Sie sind kein Teil der eigentlichen Simulation – sie rufen lediglich die (menschlich geschriebenen) Kernklassen auf und zeichnen deren Zustände mit matplotlib auf.

---

Was ist das?

Dieses Projekt simuliert ein Netzwerk von spiking Neuronen (Aktionspotenziale statt reiner Aktivierungswerte) und erweitert es um ein simuliertes Hormon-/Neuromodulator-System. Dieses kann – analog zu Dopamin, Adrenalin & Co. – während der laufenden Simulation Eigenschaften einzelner Neuronen in Echtzeit verändern (z. B. Schwellwert, Feuerrate, Reifzeit) und dient dabei gleichzeitig als einer der Lernmechanismen des Netzes.

Das System ist vollständig in PyTorch umgesetzt und kann auf der GPU laufen.

Kernideen

• Spiking Neuronen mit Ruhepotential, Schwellwert, Refraktärzeit und Hyperpolarisation.
• Synapsen mit begrenztem Vorrat („End-Caps“): Jede Verbindung „verbraucht“ bei jedem Signal und muss sich wieder aufladen – ein einfaches Modell für Ermüdung / Neurotransmitter-Begrenzung.
• STDP (Spike-Timing-Dependent Plasticity) + Eligibility-Traces als zeitbasierte Lernregel.
• Hormonsystem: ein 3D-Chemikalien-Gitter, das diffundiert, zerfällt und Neuronen-Eigenschaften zur Laufzeit moduliert.
• Belohnungs-/Lernmodulation: Ein „dopamin-ähnliches“ Signal schaltet die synaptische Plastizität frei bzw. begrenzt sie.

---

Architektur

Das Projekt ist bewusst klein gehalten. Die eigentliche Simulation steckt in drei Dateien:

Datei	Rolle
Neuron.py	Leichtgewichtiger Datenträger für ein einzelnes Neuron (Position + Neuro-Parameter).
Neurons.py	Das „Gehirn“: hält den gesamten Zustand als (GPU-)Tensoren und enthält die komplette Simulations- und Lernlogik.
Chemistry.py	Das Hormon-/Chemie-System: 3D-Gitter, Diffusion, Zerfall und die Zuordnung „Chemikalie → Effekt auf Neuron“.

Alle übrigen Dateien sind Treiber, Tests, Demos und Visualisierungen (s. Projektstruktur).

Neuron.py

Ein Neuron ist im Kern nur ein Bündel von Parametern, das in Neurons in Tensoren überführt wird:

• Position (3D), death_probability, axon_delay (Signal-Verzögerung), output_sign (erregend/hemmend, ~80 % erregend).
• Neuro-Parameter: soma_hyperpolarisation, tau (Spannungs-Zeitkonstante), soma_threshold (+ _adaption_rate), refractory_period, threshold_tau, voltage, input_buffer.

Neurons.py

Neurons reserviert alle Zustände vorab als Tensoren (Kapazität-basiert) und hält sie zusammen auf einem Device. Die wichtigsten Bausteine:

• Verbindungen: connection_start/end, connection_active, dendrits_resistant (synaptischer Widerstand), dendrits_eligibility_trace.
• End-Caps (synaptischer Vorrat): end_caps_stock, end_caps_max_stock, Refill-Rate, Stress-Counter – modelliert begrenztes „Material“ und Ermüdung.
• Neuronen-Zustand: voltage, adaptiver threshold, threshold_adaption_rate, refractory_period, hyperpolarisation, energy, verschiedene tau-Werte.
• Herzfrequenz (heart_rate, Basis 100, Bereich 50–200): wirkt als globaler „Pump-Faktor“ auf Diffusion, Refill und Energie.
• Lernen: base_learning_factor (0.99), base_learning_rate (0.05), current_learning_factors (wird vom Hormonsystem moduliert).
• Spike-Buffer (Ringpuffer): für die zeitliche Ausbreitung über axon_delay.

Simulations-Loop (update(dt))

Jeder Tickschritt läuft durch eine feste Pipeline:

1. Chemie (alle 5. Schritte, Subsampling): Zerfall + Diffusion der Chemikalien, danach Neuberechnung der pro-Neuron-Effekte.
2. _update_decay: exponentieller Zerfall von Spannung & Schwellwert (über tau), Energiebilanz, Nachfüllen der End-Caps (skaliert mit Herzfrequenz).
3. _update_values: Anwenden der chemischen Modulationen, Integration der Eingabe, Refraktär-Check, Feuer-Entscheidung (Schwelle überschritten + genug Energie), danach Post-Fire-Updates (Reset auf Hyperpolarisation, Schwellwert-Adaption, Energiekosten, Spike in den Buffer mit axon_delay).
4. _neurons_fire_signals: Verarbeiten der angekommenen Spikes (Axon-Verzögerung), Verbrauch der End-Caps, Stress-/Anpassungslogik.
5. _dendrits_fire_signals: Zustellung des Signals an die Zieldendriten (load / resistance in den input_buffer), LTD-Logik.
6. _stdp: STDP-Berechnung über Eligibility-Traces + Myelinisierung (Anpassung der axon_delay).
7. _update_traces_and_learning: Trace-Abbau + Lernschritt (Widerstand ändert sich – nur wenn ein Belohnungssignal vorliegt).

Die Performance-kritischen Teile laufen als @torch.jit.script-Kernels (_jit_physics_kernel, _jit_stdp_kernel, _jit_apply_learning_inplace, _jit_end_caps_kernel), um Python-Loop-Overhead auf der GPU zu vermeiden.

---

🧪 Das simulierte Hormonsystem

Kernfeature: Das Hormonsystem kann in der Laufzeit Eigenschaften einzelner Neuronen modifizieren und ist damit einer der Lernmechanismen des Netzes.

Aufbau (aus Chemistry.py)

1. 3D-Chemikalien-Gitter. Für bis zu max_chemistry verschiedene Chemikalien existiert ein eigenes 3D-Volumen (size³). In jeder Zelle ist die aktuelle Konzentration gespeichert.

2. Zuordnung „Chemikalie → Effekt“ über ein Register. chemistry_register ist ein uint8-Tensor der Form [Chemikalien, Slots, 2]:

   • Slot 0 = Index des Ziel-Effekts (welche Eigenschaft wird beeinflusst).
   • Slot 1 = Stärke (0–255, wobei 128 = neutral).

   Aus diesem Register wird die Matrix chem_matrix ([Effekte × Chemikalien]) vektorisiert kompiliert (_compile_chemistry_matrix, via index_put_ mit Akkumulation). So lässt sich sauber definieren, welche Chemikalie auf welche Eigenschaft wie stark wirkt.

3. Ausschüttung.

   • inject_chemical(chem_id, x, y, z, amount) – lokale Injektion an einem Punkt.
   • inject_global_chemical(chem_id, amount) – simuliert einen weitreichenden Neuromodulator (z. B. Dopamin), der über das gesamte Volumen verteilt wird.

4. Dynamik: Zerfall + Diffusion (update_chemistry_dynamics).

   • Zerfall: chemistry *= exp(-decay_rate * dt).
   • Diffusion: ein Gauß-Kern wird per conv3d (grouped) als Weichzeichnung über das Gitter gefaltet; die Mischrate skaliert mit der aktuellen Herzfrequenz.
   • Konzentrationen werden auf ≥ 0 geklemmt.

5. Wirkung auf die Neuronen (update_chemistry_effects).

   • Jedes Neuron samplet die lokale Konzentration an seiner Gitterposition.
   • Die Konzentration wird auf einen Rezeptor-Bereich geklemmt (max_chemistry_receptors).
   • current_chem_mod = chem_matrix @ lokale_Konzentrationen → liefert pro Neuron und pro Effekt den aktuellen Modulationswert.

Welche Eigenschaften werden modifiziert?

Das System kennt diese modifizierbaren Effekte (die jeweiligen Stärken-Faktoren stehen in chemistry_max_effect):

Effekt	Wirkung auf das Neuron
voltage	verschiebt die Membranspannung
threshold	verschiebt den Feuerschwellwert
threshold_tau / voltage_tau	verändern die Zeitkonstanten (wie schnell Spannung/Schwelle zerfallen)
threshold_adaption_rate	wie stark der Schwellwert nach jedem Spike angehoben wird
refractory_period	Dauer der Refraktärzeit
hyperpolarisation	Stärke der Hyperpolarisation nach dem Feuern
learning_rate	schaltet die synaptische Plastizität frei / begrenzt sie
heart_rate	beeinflusst die globale „Pump“-Rate
noise	fügt stochastisches Rauschen hinzu
energy	beeinflusst den Energie-Bestand

Zur Laufzeit-Modifikation: Weil current_chem_mod in jedem Tickschritt neu aus der lokalen Konzentration berechnet wird und die Effekte direkt in die Neuronen-Physik (_update_values, _update_decay, _update_traces_and_learning) eingehen, lassen sich Eigenschaften eines Neurons während der laufenden Simulation gezielt verändern – z. B. das Ausschüttungsfenster unten: Sobald das Hormon ankommt, steigt der effektive Schwellwert und das Neuron feuert seltener.

Was man hier sieht: Zwei zusammenhängende Kurven. Orange (rechte Achse) = die Hormon-Konzentration am Neuron: sie steigt, wenn das Hormon ausgeschüttet wird (lila Fläche), und fällt, wenn es abgebaut wird. Blau (linke Achse) = der effektive Feuerschwellwert – und der folgt der Hormon-Konzentration: Hormon da → Schwelle hoch (~15), Hormon abgebaut → Schwelle zurück auf den Basiswert (graue gestrichelte Linie, ~5). Der Abfall am Ende ist also nicht einfach so, sondern das Hormon wird abgebaut (orange → 0). Die roten X zeigen: während die Schwelle erhöht ist, feuert das Neuron seltener. Genau das ist die Laufzeit-Modifikation – der Schwellwert ist eine Funktion der momentanen Hormon-Konzentration.

Das Hormonsystem als Lernmechanismus

Der Effekt learning_rate ist der entscheidende Brückenschlag: In _update_values wird aus dem modulierten Wert über eine tanh-Glättung ein Lernfaktor berechnet (current_learning_factors, Bereich 0.8–1.2), und in _update_traces_and_learning wird der synaptische Widerstand nur umso geändert, wenn dieses Signal an der Ziel-Synapse anliegt.

Zusammen mit STDP (Prä-zu-Post-Timing baut Eligibility-Traces auf) entsteht ein belohnungs- / kontextgesteuertes Lernen nach dem Muster:

Prä feuert → Post feuert (Timing) → Belohnung (Hormon) an Ort und Stelle → Synapse wird gestärkt (Widerstand sinkt).

Ohne das Hormon bleibt die Plastizität praktisch wirkungslos – das Hormon schaltet das Lernen frei. Genau das zeigt die Grafik unten: Der synaptische Widerstand fällt deutlich, während die Eligibility-Trace aktiv ist.

Was man hier sieht: Blau = synaptischer Widerstand (sinkt = die Synapse wird stärker), orange gestrichelt = Eligibility-Trace (die STDP-Lernspur, die bei Prä-zu-Post-Timing aufgebaut wird). Solange das Belohnungshormon an der Synapse anliegt, sinkt der Widerstand – die Verbindung wird also durch das Hormon gezielt gestärkt. Ohne Hormon bliebe der Widerstand unverändert.

---

Weitere Grafiken & Animationen

🎬 3D-Visualisierung (Video)

Interaktive 3D-Szene aus main.py / der Web-App: Neuronen als Punkte in einem 3D-Raum (dünne Linien = Synapsen), dargestellt auf einem 3D-Raster. Die HUD-Anzeige oben links zeigt Simulationszeit, Chemikalien-Masse, globale Aktivität (Hz), FPS, SPS und RTF. Über [SPACE] werden Anästhetika injiziert, mit [R] werden die Chemikalien zurückgesetzt.

Vorschau (GIF – läuft direkt im README ab):

Volles Video (höhere Auflösung & Länge) – Bild anklicken, um es abzuspielen:

▶️ MP4 direkt öffnen (~21 MB) – spielt im Browser ab.

🌀 Animationen (GIF)

2D-Hormon-Diffusion – wie ein Hormon sich auf einer Fläche ausbreitet:

Was man hier sieht: Ein Hormon wird im Zentrum der 2D-Fläche ausgeschüttet (heller Kern) und breitet sich mit der Zeit sichtbar nach außen aus – der helle Kern wird größer und flacher, die Konzentration verteilt sich über die ganze Fläche (Farbverlauf + Farbleiste rechts = Konzentration). Das ist exakt der Mechanismus aus Chemistry.py (Gauß-Blur als Diffusion + exponentieller Zerfall), nur in 2D und ohne Neuronen dargestellt. Man sieht also, wie sich ein ausgeschüttetes Hormon in der „Flüssigkeit“ ausbreitet und wieder abklingt.

Kleines 2D-Netz, das feuert – Spike-Propagation durch echte Neuronen (Neurons.py):

Was man hier sieht: Ein kleines Netz aus echten Neuronen, aufgebaut als Kette von links (Input) nach rechts. Der linke Input-Neuron wird periodisch angeregt und feuert. Der Spike läuft als Welle von links nach rechts durch das Netz: Der jeweils erreichte Knoten leuchtet kurz weiß/gelb auf, und die gelbe Kante markiert die aktive Signalweiterleitung an den nächsten Neuron. Man sieht die zeitliche Ausbreitung eines Spike – genau das, was in main.py im 3D-Netz live passiert.

🖼️ Einzelbilder

Spike-Response eines einzelnen Neurons

Was man hier sieht: Ein einzelnes Neuron im klassischen Leaky-Integrate-and-Fire-Verhalten. Unter konstanter Erregung steigt die Membranspannung (blau) an, bis sie die Feuerschwelle (orange gestrichelt) erreicht – dann feuert das Neuron (rotes X, auf der Schwelle) und die Spannung fällt sofort in die Hyperpolarisation (negativ) zurück. Danach beginnt der Anstieg von vorn. Die Schwellwert-Linie wandert leicht nach oben, weil sie sich nach jedem Spike anpasst (Schwellwert-Adaption).

Netzwerk-Topologie

Was man hier sieht: 60 Neuronen (Punkte, Farbe = zufällige Aktivitäts-Intensität) mit zufälligen Synapsen (graue Linien). Dient nur als schematische Darstellung der Vernetzung – keine reale Simulation.

Weitere Assets (vom Autor erstellt):

• Graphics/NeuronVisualisation.png – Neuron-Visualisierung.
• Graphics/3D-visualisation-with-chemicals.mp4 – 3D-Aufzeichnung des Netzwerks mit Chemikalien (siehe Video oben).

📌 Hinweis zur Herkunft: Die Dateien grafik_*.png, anim_hormone_diffusion.gif und anim_net_spiking.gif wurden mit den KI-generierten Skripten generate_readme_graphics.py bzw. generate_animation_graphics.py erzeugt (nur zur Visualisierung). anim_3d_preview.gif und poster_3d_visualisation.png wurden aus dem Autoren-Video abgeleitet. NeuronVisualisation.png, 3D-visualisation-with-chemicals.mp4 und die 3D-Szene stammen vom Autor.

---

Projektstruktur

Datei	Zweck
Neuron.py	Datenträger für ein einzelnes Neuron.
Neurons.py	Kern: Gehirn, Simulations-Loop, STDP, End-Caps, Lernen.
Chemistry.py	Kern: Hormon-/Chemie-System (Gitter, Diffusion, Effekte).
main.py	Interaktive 3D-Matplotlib-Visualisierung (Sliders, Neuronen-Inspector, Chemie-Injektion).
simualation-app.py	Web-App (Flask + Socket.IO) für die Simulation im Browser.
first_try_learning.py	Lern-Demo: Agent mit Sensoren (PyQtGraph).
second_try_learning.py	Weiterentwicklung der Lern-Demo (mehr Neuronen, feineres Sensor-Setup).
pawlows_dog_test.py	Pawlow-Experiment: konditionierte Reaktion via Dopamin-Belohnung.
xor2.py / xor_gen.py / xor_learn.py	XOR-Gate: manuelles Timing, genetischer Algorithmus, Dopamin-Lernen.
nand.py	NAND-Gate als sauberes Timing-Beispiel.
test.py / chemistry_test.py	Funktionale Tests für Neuronen-Physik bzw. Chemie-System.
first_test.py	3D-OpenGL-Demo (PyQtGraph).
Visualization_STDP.py	Visualisierung von STDP / Widerstand / End-Cap-Vorrat.
benachmark.py	Performance-Benchmark über verschiedene Netzwerkgrößen.
bottelneck_check.py	Profiling / Bottleneck-Analyse.
tests.ipynb	Interaktive Notebook-Tests.
generate_readme_graphics.py	KI-generiert, nur zur Generierung der README-Grafiken (PNG).
generate_animation_graphics.py	KI-generiert, nur zur Generierung der README-Animationen (GIF).
templates/, static/	Frontend der Web-App.
Graphics/	Bilder & Videos.

Hinweis: Die Dateinamen enthalten einige Tippfehler (z. B. simualation-app.py, bottelneck_check.py). Sie wurden bewusst nicht umbenannt, um Verweise und Historie nicht zu brechen.

---

Voraussetzungen & Installation

# Python 3.10+ empfohlen
pip install torch matplotlib numpy
# für die Demos / die Web-App zusätzlich:
pip install pyqtgraph flask flask-socketio

Für GPU-Beschleunigung: eine CUDA-fähige torch-Installation (das Projekt erkennt die GPU automatisch und fällt sonst auf CPU zurück).

Ausführen

# Interaktive 3D-Visualisierung (empfohlen zum Ansehen)
python main.py

# Web-App
python simualation-app.py

# Tests
python test.py
python chemistry_test.py

# Demos / Experimente
python pawlows_dog_test.py
python nand.py
python xor2.py

# Performance
python benachmark.py
python bottelneck_check.py

Die README-Grafiken/-Animationen neu erzeugen (nur Visualisierung, KI-generiert):

python generate_readme_graphics.py     # PNG-Grafiken
python generate_animation_graphics.py # GIF-Animationen (Diffusion + 2D-Netz)

---

Bekannte Einschränkungen (PoC)

• Parameter sind experimentell und nicht physikalisch kalibriert (z. B. end_caps_*, trace_tau, Chemie-Raten).
• Kein vollständiger Testablauf / CI; Tests sind manuelle Skripte.
• Keine saubere API / Typisierung / Paketstruktur – bewusst als lose Skripte gehalten.
• Performance ist nicht das Ziel; Optimierungen (Batching, Custom-Kernels, Speicherlayout) stehen noch aus.
• Keine Garantie für korrekte biologische Plausibilität – es ist ein konzeptueller Ansatz.

---

Dieses Repository ist ein Proof of Concept aus Dezember 2025. Code: menschlich geschrieben (mit KI-gestützten Teilstellen). Diese README: vollständig KI-generiert. Nicht für produktiven Einsatz.