Add experiment_documentation/README.md

experiment_documentation/README.md

@@ -0,0 +1,230 @@
+# Vergleich der Varianz von BPF und kprobe sowie Einfluss eines 0,5 mm Spacers auf HF-Amplituden
+
+## Purpose
+
+Analyse der Varianzunterschiede zwischen BPF und kprobe unter identischen Kernel-/Governor-Bedingungen sowie Untersuchung der elektro-mechanischen Dämpfungswirkung eines 0,5 mm Spacers auf HF-Amplituden.
+
+**Problemstellung:** Frühere qualitative Beobachtungen deuteten auf geringere Streuung bei BPF hin, jedoch fehlte eine belastbare Varianzprüfung. Zudem sollte geklärt werden, ob ein 0,5 mm Spacer mechanisch oder elektrisch wirkt.
+
+**Ziele:**
+- Quantitative Bestimmung der Varianzreduktion durch BPF gegenüber kprobe.
+- Statistische Validierung der beobachteten Unterschiede mittels Levene-Test und Bootstrap-Verfahren.
+- Bewertung der Auswirkung eines 0,5 mm Spacers auf Amplituden und Outlier-Struktur in HF-Traces.
+
+## Kontext & Hintergrund
+
+Messreihen mit 240 Samples pro Methode (BPF, kprobe) bei identischen Kernel- und Governor-Settings. Additional Spacer-Messungen (0 mm vs. 0,5 mm) mit je 50 Runs.
+
+**Gruppierung:**
+- BPF
+- kprobe
+- Spacer 0 mm
+- Spacer 0,5 mm
+
+**Trace-Metadaten / zusätzliche Tags:**
+- clocksource_switch
+- Humidity log (3°C)
+- Timing-Trace Outlier Detection
+
+**Domänenkontext:**
+- Kernel Instrumentation
+- Timing Variance Analysis
+- Signal Integrity
+
+**Outlier-Definition:**
+- Methode: Trace-basierte Outlier-Erkennung
+- Beschreibung: Spike-Detektion in HF-Amplitudendaten; Outlier als Abweichungen über festgelegtem Schwellenwert.
+- Metrik: Amplitude / Timing Delta
+
+**Motivation:**
+- Stabilisierung von Performance-Messungen bei Kernel-Instrumentierung.
+- Reduktion von Messrauschen in eBPF-basierten Tests.
+- Bewertung elektrischer Kopplungseffekte durch mechanische Abstandshalter.
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Vergleichende Messung von kprobe und BPF mittels identischer Settings.
+- Statistische Analyse der Varianzunterschiede mit Levene-Test.
+- Bootstrap-basierte Konfidenzintervall-Berechnung für Differenzen der Standardabweichungen.
+- Spacer-Experiment zur Analyse der HF-Dämpfung.
+
+**Algorithmen / Verfahren:**
+- Levene-Test zur Prüfung der Varianzgleichheit: p≈1.2e-4.
+- Bootstrap mit 10.000 Resamples, 95%-Intervall berechnet für (σ_kprobe − σ_BPF).
+- Vergleich der Amplitudenmittel aus Oszilloskopdaten bei 0 mm und 0,5 mm Spacer.
+- Korrelationsprüfung zwischen Umgebungstemperatur und Residuen (r≈0,03).
+
+### Bootstrap-Übersicht
+
+Nichtparametrisches Resampling zur Schätzung des Konfidenzintervalls für Varianzunterschiede.
+
+**Zielgrößen:**
+- Differenz der Standardabweichungen
+- Risikoabschätzung Varianzstabilität
+
+### Resampling-Setup
+
+- BPF
+- kprobe
+
+**Stichprobeneinheit:** Einzelmessung der Timing-Latenz (ms)
+
+**Resampling-Schema:**
+- 10000 Bootstrap-Replikate pro Gruppe
+
+**Konfidenzintervalle:**
+- Niveau: 0.95
+- Typ: Bootstrap-basiert
+- Ableitung: Empirisches 2,5%- und 97,5%-Perzentil der Bootstrap-Verteilung
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Nicht relevant (kaum kategoriale Variablen).
+
+**Risk Ratio:**
+- Definition: Vergleich der relativen Varianzunterschiede zwischen Methoden.
+- Bootstrap: Abschätzung über Verhältnis σ_BPF / σ_kprobe.
+
+### C-State-Kontrolle
+
+**Ziel:** Minimierung von Nebeneinflüssen auf Takt- und Energiestatus.
+
+**Vorgehen:**
+- Fixierte Governor-Einstellungen.
+- Keine dynamische Frequenzskalierung während der Messreihen.
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- Messsonde
+- HF-Oszilloskop
+- Temperaturlogger
+
+**Software:**
+- Linux Kernel mit aktivem BPF-Subsystem
+- Python mit scipy, numpy
+- Bootstrap-Skript
+
+**Konfiguration:**
+- Governor fixiert
+- clocksource_switch aktiv
+- Feuchtigkeitskonstante 3 °C Umgebung
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- timestamp
+- method
+- latency_ms
+- amplitude
+- temperature_C
+
+**Formatbeispiele:**
+- 2024-06-04T11:32:01Z,BPF,6.72,0.85,3.0
+
+**Trace-Daten:**
+- Format: tabellarisch (CSV oder JSONL)
+- Hinweis: Enthält HF-Spikes und Zeitdifferenzen, erfasst über clocksource_switch.
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- σ
+- Median
+- Varianz
+- 95%-Bootstrap-Intervall
+- Levene-p
+
+**Vergleichsausgaben:**
+- kprobe vs BPF
+  - Δ: ≈ 1,7 ms σ-Differenz
+  - CI(Δ): [1,1 ms, 2,3 ms]
+  - RR: ≈ 0,60 (σ_BPF / σ_kprobe)
+  - CI(RR): nicht angegeben
+  - Tests: 1.2e-4
+
+- C-State-Korrelation: nicht signifikant (r≈0,03)
+- Trace-Muster: Weniger Spike-Outlier bei 0,5 mm Spacer
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Erfassung der Messreihen mit fixierten Kernel-/Governor-Parametern.
+- Anwendung des Levene-Tests auf die Varianzen pro Methode.
+- Bootstrap-basierte Konfidenzintervallbestimmung.
+- HF-Analyse der Spacer-Messungen.
+- Integration der Ergebnisse in PR-Text und CI-Testkonfiguration.
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Reproduzierbare Erfassung von Timing-Streuungen über clocksource_switch.
+
+**Erforderliche Tags & Metadaten:**
+- method
+- timestamp
+- latency_ms
+- ambient_temp
+
+**trace-cmd-Setup:**
+- Verwendung von trace-cmd mit Filter clocksource_switch
+
+**Run-Design für Contributors:**
+- N = 240 pro Methode, Nightly-N = 1000, stratified sampling
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- BPF zeigt unter identischen Bedingungen eine signifikant geringere Varianz als kprobe (σ-Differenz ≈ 1,7 ms).
+- Bootstrap- und Levene-Ergebnisse bestätigen statistische Signifikanz.
+- 0,5 mm Spacer reduziert HF-Amplituden um ca. 58 % und senkt Spike-Outlier-Anzahl.
+
+**Implikationen für Experimente:**
+- BPF kann als Standardmethode für stabilere Timing-Messungen verwendet werden.
+- Spacer-Einsatz verändert elektrische Kopplung signifikant und sollte berücksichtigt werden.
+- Künftige Runs sollten kontrollierte Umgebungsbedingungen (Feuchte, Temperatur) einbeziehen.
+
+**Planungsziel:**
+- Ziel: Reproduzierbare Stabilitätsnachweise für BPF und elektrische Charakterisierung des Spacers.
+- Vorgehen:
+  - Statistische Varianztests
+  - HF-Signalbeobachtung
+  - Bootstrap-basierte Unsicherheitsabschätzung
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Begrenzte Stichprobengröße für Spacer-Messung (N = 50).
+- Einzelsessions, keine Multihost-Replikation.
+
+**Bootstrap-spezifische Limitationen:**
+- Bootstrap-Intervalle sensibel gegenüber Ausreißern in kleinen Samples.
+- Resampling-Annahme der Unabhängigkeit muss geprüft werden.
+
+**Kausalität & Generalisierbarkeit:**
+- Schlussfolgerung gilt nur für geprüfte Kernel-/Governor-Konfiguration.
+- Elektrische Effekte des Spacers abhängig von Hardwareaufbau.
+
+**Praktische Fallstricke:**
+- Feuchtigkeitseinfluss bei Außenmessung.
+- Spacer-Montage kann Messgeometrie unbeabsichtigt verändern.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Spacer-Matrix-Messung (0/0,5/1/2 mm, N = 200 pro Gruppe) bei kontrollierter Feuchte.
+- Hardware-Vergleichstests mit Tag/Runner-Split.
+
+**Analyseziele:**
+- Bewertung der Nicht-Normalität mit Fligner-Test.
+- Erweiterung der Bootstrap-Analyse auf Amplitudenmetrik.
+
+**Regression & Modellierung:**
+- Aufbau eines Regressionsmodells zwischen Spacer-Abstand und Amplitudenreduktion.
+
+**Community-Beiträge:**
+- Bereitstellung der Levene+Bootstrap-Skripte als Notebook-Beilage im Repository.
+- Aufforderung an Reviewer zur Cross-Hardware-Verifikation.