Add artifact_3_documentation/README.md

artifact_3_documentation/README.md

@@ -0,0 +1,188 @@
+# Analyse von band_width-Streuung und Mixeinflüssen (Runs #36–#39)
+
+## Purpose
+
+Untersuchung der Ursachen für Streuung in band_width und deren Beziehung zu aux-Werten und zum Anteil near-expiry-unpinned.
+
+**Problemstellung:** Unklar, ob erhöhte band_width-Werte bei aux=3 auf systemische Drift oder auf veränderte Stratum-Mischung zurückzuführen sind.
+
+**Ziele:**
+- Erkennen, ob band_width-Streuung durch aux-Parameter oder durch Mix-Unterschiede entsteht
+- Abgrenzen von Drift-Phänomenen und struktureller Streuung
+- Prüfen der Reproduzierbarkeit durch Runs mit identischem Setup
+
+## Kontext & Hintergrund
+
+Runs #36–#39 mit unterschiedlichen aux-Werten und definierten Mix-Zusammensetzungen.
+
+**Gruppierung:**
+- aux
+- Stratum-Proxy
+
+**Trace-Metadaten / zusätzliche Tags:**
+- Monotonic-Δt
+- tz_offset
+
+**Domänenkontext:**
+- Systemverhalten unter variierenden Workload-Strata
+- Mix-abhängige Bandbreite in Metriken
+
+**Outlier-Definition:**
+- Methode: IQR-basierte Identifikation
+- Beschreibung: band_width-Ausreißer werden über Median + IQR definiert.
+- Metrik: band_width
+
+**Motivation:**
+- Reduktion von Fehlinterpretationen experimenteller Drift
+- Trennung von Eingangsvariabilität und tatsächlichem Steuerungseffekt
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Aggregierte Run-Ansicht mit Median- und IQR-Werten pro Kennzahl
+- Vergleich von Δband_width (Median über Fenster) zur Stabilitätseinschätzung
+
+**Algorithmen / Verfahren:**
+- Berechnung von band_width (Median, IQR)
+- Berechnung von Δband_width zwischen erstem und letztem Fenster
+- Trennung von retry_tail_p99 nach Hotspot und Rest (Median, IQR)
+- Ermittlung des near-expiry-unpinned-Anteils als Stratum-Proxy
+
+### Bootstrap-Übersicht
+
+Resampling zur Stabilitätsprüfung von statistischen Kennwerten.
+
+**Zielgrößen:**
+- Median band_width
+- IQR band_width
+
+### C-State-Kontrolle
+
+**Ziel:** Überprüfung der zeitlichen Kohärenz zwischen Runs
+
+**Vorgehen:**
+- Prüfung auf keine negativen Monotonic-Δt
+- Sicherstellung eines konstanten tz_offset
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- Homogene Systemumgebung für Runs
+
+**Software:**
+- Identische Trace- und Messinfrastruktur
+
+**Konfiguration:**
+- Gleiche byteweise Parameterkonfiguration für Runs mit unterschiedlichem aux
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- band_width_median
+- band_width_iqr
+- delta_band_width
+- retry_tail_p99_hotspot
+- retry_tail_p99_rest
+- near_expiry_unpinned_ratio
+- jobs_per_walltime
+
+**Formatbeispiele:**
+- band_width_median=0.35, band_width_iqr=0.12
+- delta_band_width=-0.02
+
+**Trace-Daten:**
+- Format: CSV oder JSON mit Zeitstempeln und aux-Parametern
+- Hinweis: Monotonicität und Zeitzonenoffset müssen konsistent sein
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- Median + IQR von band_width über Fenster
+- Δband_width pro Run
+- retry_tail_p99 Hotspot/Rest
+
+**Vergleichsausgaben:**
+- aux=2 vs aux=3
+  - Δ: Δband_width-basierter Unterschied zwischen Mittelwerten
+  - CI(Δ): 95%-Konfidenzintervall nach Bootstrap
+  - RR: Verhältnis der band_width-Ausreißerhäufigkeit
+  - CI(RR): 95%-Konfidenzintervall aus Resampling
+
+- C-State-Korrelation: Keine zeitbedingte Drift durch externe Zeitsprünge
+- Trace-Muster: Breitere band_width nur bei höherem near-expiry-unpinned-Anteil
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Runs mit aux=2 und aux=3 auswerten
+- Mix-Anteil near-expiry-unpinned bestimmen
+- Kennzahlen berechnen und nach Stratum-Proxy gruppieren
+- Δband_width prüfen
+- Bootstrap-Resampling für Stabilität durchführen
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Reproduzierbare Analyse der band_width-Streuung unter kontrolliertem Mix
+
+**Erforderliche Tags & Metadaten:**
+- aux
+- Stratum-Proxy
+- Monotonic-Δt
+- tz_offset
+
+**trace-cmd-Setup:**
+- Verwendung konsistenter Zeitquellen
+- Keine Anpassung von Zeitzonen während der Messung
+
+**Run-Design für Contributors:**
+- Identische Jobs/Walls, Variation nur in aux oder Mix-Zusammensetzung
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- band_width-Streuung korreliert stärker mit near-expiry-unpinned-Anteil als mit aux-Wert
+- Δband_width bleibt häufig klein trotz breiter Bänder
+- Keine Hinweise auf systemische Drift
+
+**Implikationen für Experimente:**
+- Zukünftige Vergleiche müssen Mix-Anteile fixieren oder kontrollieren
+- aux-abhängige Effekte erst interpretieren, wenn Strata vergleichbar sind
+
+**Planungsziel:**
+- Ziel: Validierung des Einflusses von aux unter konstantem Mix
+- Vorgehen:
+  - Mix-Freeze-Ansatz: near-expiry-Anteil fixieren oder Runs filtern
+  - Aux=2 vs. Aux=3 erneut vergleichen
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Fehlerhafte Stratum-Zuordnung kann scheinbare Drift erzeugen
+- Messungen ohne Mix-Kontrolle führen zu Scheinkorrelationen
+
+**Bootstrap-spezifische Limitationen:**
+- Verzerrung bei zu kleinen Stichproben pro aux-Gruppe
+
+**Kausalität & Generalisierbarkeit:**
+- Beobachtete Korrelation nicht notwendig kausal
+- Gültigkeit auf ähnliche Strata beschränkt
+
+**Praktische Fallstricke:**
+- Unzureichende Kontrolle von near-expiry-unpinned macht Vergleich nicht belastbar
+- Zeitinkonsistenzen könnten unbemerkt Streuung verstärken
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Durchführung des Mix-Freeze-Experiments mit fixiertem near-expiry-Gehalt
+
+**Analyseziele:**
+- Isolieren des echten aux-Effekts auf band_width unter konstantem Inputprofil
+
+**Regression & Modellierung:**
+- Statistische Modellierung von band_width als Funktion von aux und Stratum-Proxy
+
+**Community-Beiträge:**
+- Bereitstellung standardisierter Trace-Vorlagen und Mix-Kontrollrichtlinien