From 0cbda6c07ace6c1df252d9476d7e69d32f4e1bfb Mon Sep 17 00:00:00 2001
From: Mika <kontakt@donau2space.de>
Date: Sat, 21 Mar 2026 17:02:40 +0000
Subject: [PATCH] Add experiment_documentation/README.md

---
 experiment_documentation/README.md | 194 +++++++++++++++++++++++++++++
 1 file changed, 194 insertions(+)
 create mode 100644 experiment_documentation/README.md

diff --git a/experiment_documentation/README.md b/experiment_documentation/README.md
new file mode 100644
index 0000000..26c3690
--- /dev/null
+++ b/experiment_documentation/README.md
@@ -0,0 +1,194 @@
+# Interaktion von Affinität und Parallelität im Verteilungssystem
+
+## Purpose
+
+Analyse der Wechselwirkungen zwischen Affinität und Parallelität in einem verteilten System hinsichtlich Bandbreite (IQR) und Retry‑Tail (p99‑Metrik).
+
+**Problemstellung:** Der bisherige Affinitäts‑Effekt skaliert nicht linear mit Parallelität; es ist unklar, ob dieser Effekt durch Systemlast (Queueing) verstärkt wird.
+
+**Ziele:**
+- Quantifiziere den Einfluss der CPU‑Affinität auf Bandbreite und Tail‑Latenzen unter variierender Parallelität.
+- Untersuche, ob sich Affinitäts‑ und Parallelitäts‑Effekte additiv oder interaktiv verhalten.
+- Validiere, ob Queueing‑Sättigung den Affinitäts‑Effekt moduliert.
+
+## Kontext & Hintergrund
+
+Laufdaten der Runs #28–#30 mit Metriken für Bandbreite als IQR (in Stunden) und retrytail_p99 relativ zu einer Baseline.
+
+**Gruppierung:**
+- Affinitäts‑Zustände (enforced, randomized)
+- Parallelität (2×, 4×)
+
+**Trace-Metadaten / zusätzliche Tags:**
+- setup_fingerprint
+- policy_hash
+- Burst‑Start‑Fenster
+
+**Domänenkontext:**
+- Verteilte Systeme
+- CPU‑Affinität
+- Thread‑Parallelität
+- Queueing‑Effekte
+
+**Outlier-Definition:**
+- Methode: IQR‑Methode
+- Beschreibung: Bandbreite als Interquartilsabstand (IQR) über Messlaufzeit.
+- Metrik: band_width (h)
+
+**Motivation:**
+- Erkennen von Interaktionen zwischen Scheduling‑Mechanismen und Laststeuerung.
+- Ableitung stabiler Performance‑Regionen bei verschiedenen Parallelitätsstufen.
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Drei Runs (#28–#30) mit variierender Parallelität und Affinität.
+- Vergleich der relativen band_width (IQR) und retrytail_p99 gegen Baseline.
+- Berechnung der Effektgrößen (Differenzen und Prozentveränderungen).
+
+**Algorithmen / Verfahren:**
+- Identifiziere Baseline Run (#28 randomized, 4×).
+- Berechne Δband_width und Δretrytail_p99 für Varianten.
+- Interpretation der Interaktionsstärke als Abweichung vom additiven Modell.
+
+### Bootstrap-Übersicht
+
+Nicht durchgeführt; analytische Betrachtung auf aggregierten Einzelwerten.
+
+**Zielgrößen:**
+- band_width
+- retrytail_p99
+
+### Resampling-Setup
+
+- Run‑Level (Affinität × Parallelität)
+
+**Stichprobeneinheit:** Einzel‑Run
+
+**Resampling-Schema:**
+**Konfidenzintervalle:**
+- Niveau: 0.95
+- Typ: analytisch (nicht berechnet)
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Nicht relevant; Kennzahlen sind kontinuierlich.
+
+**Risk Ratio:**
+- Definition: Nicht anwendbar; relative Effekte als Prozentdifferenzen notiert.
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- Mehrkernprozessor mit konfigurierbarer Thread‑Affinität
+
+**Software:**
+- System‑Scheduler mit Affinitätssteuerung
+- Messframework zur Laufzeitüberwachung
+
+**Konfiguration:**
+- Parallelitätslevels (2×, 4×, geplant 8×)
+- Affinitätsmodi: enforced, randomized
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- run_id
+- affinity_mode
+- parallelism
+- band_width_iqr_h
+- retrytail_p99_delta
+
+**Formatbeispiele:**
+- #29, enforced, 2x, 3.9, -18%
+
+**Trace-Daten:**
+- Format: CSV
+- Hinweis: Kompakte Effekt‑Tabelle mit Zeitmetriken und Relativwerten.
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- band_width_iqr
+- retrytail_p99_delta
+
+**Vergleichsausgaben:**
+- #28 randomized 4× vs #28 enforced 4×
+  - Δ: band_width −1.7 h, retrytail_p99 +11%
+- #29 enforced 2× vs #30 randomized 2×
+  - Δ: band_width +0.3 h, retrytail_p99 +4%
+
+- Trace-Muster: Veränderte Queue‑Sättigung korreliert mit verringertem Affinitäts‑Einfluss.
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Definiere Baseline mit randomized Affinität und 4× Parallelität.
+- Führe Runs mit variierender Affinität (enforced/off) bei fixierter Parallelität durch.
+- Vergleiche Mittelwerte der Kennzahlen über Runs.
+- Bewerte, ob Δband_width und Δretrytail_p99 proportional, subadditiv oder superadditiv interagieren.
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Erfassung konsistenter Performance‑Kennzahlen über Runs.
+
+**Erforderliche Tags & Metadaten:**
+- run_id
+- affinity_mode
+- parallelism
+- retrytail_p99
+- band_width_iqr_h
+
+**trace-cmd-Setup:**
+- Verwende identisches setup_fingerprint, policy_hash und Burst‑Start‑Fenster pro Vergleichsgruppe.
+
+**Run-Design für Contributors:**
+- Ändere pro Run nur einen Parameter (Single‑Toggle‑Prinzip).
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Affinitäts‑Effekt nimmt mit steigender Parallelität zu.
+- Bei 2× Parallelität ist der Einfluss von Affinität auf performance‑tails gering.
+- Bei höherer Systemlast (4× oder mehr) verstärkt Queueing den Affinitäts‑Effekt.
+
+**Implikationen für Experimente:**
+- Affinitätssteuerung sollte je nach Lastgrad unterschiedlich bewertet werden.
+- Eine isolierte Tuning‑Bewertung ohne Queueing‑Kontext kann zu Fehlschlüssen führen.
+
+**Planungsziel:**
+- Ziel: Vorbereitender Hochlast‑Test bei 8× Parallelität zur Validierung der Nichtlinearität.
+- Vorgehen:
+  - Wiederholung der Vergleichsreihe bei 8×.
+  - Überprüfung, ob Effekte superlinear wachsen.
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Kleine Stichprobengröße (drei Runs) limitiert statistische Aussagekraft.
+
+**Bootstrap-spezifische Limitationen:**
+- Keine Resampling‑Analyse durchgeführt.
+
+**Kausalität & Generalisierbarkeit:**
+- Kausalitäten angenommen, aber nicht experimentell isoliert bestätigt.
+
+**Praktische Fallstricke:**
+- Scheduler‑Bias möglich, wenn Threads nicht gleichmäßig verteilt werden.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Hochlast‑Run mit 8× Parallelität zur Überprüfung der Hypothese.
+
+**Analyseziele:**
+- Validiere Superlinearität des Affinitäts‑Einflusses auf band_width.
+
+**Regression & Modellierung:**
+- Erstellen eines einfachen Interaktionsmodells (Affinität × Last).
+
+**Community-Beiträge:**
+- Diskussion möglicher Visualisierungen (Differenz‑von‑Differenzen, Elastizitäts‑Plots).