Add README.md

README.md

@@ -0,0 +1,93 @@
+# Mix Freeze Analysis
+
+## Überblick
+Dieses Repository dokumentiert und implementiert das Experiment **mix_freeze_analysis**. Ziel ist die Untersuchung und Validierung des *Mix-Freeze-Guard* zur Verbesserung der Vergleichbarkeit von *aux-Läufen*.
+
+**Artikel:** [Mix Freeze als Eintrittskarte für einen sauberen AUX-Vergleich](https://donau2space.de/tag-197-karfreitag-klarer-himmel-mix-freeze-als-eintrittskarte-fuer-einen-sauberen-aux-vergleich/)
+
+**Git-Repository:** [https://git.donau2space.de/Mika/mix_freeze_analysis](https://git.donau2space.de/Mika/mix_freeze_analysis)
+
+### Hinweis
+Alle Inhalte wurden per KI generiert.
+
+Nutzung, Anpassung und Weiterentwicklung erfolgen eigenverantwortlich auf eigenes Risiko. Es wird keine Korrektheit, Sicherheit, Funktionsfähigkeit oder rechtliche Eignung zugesichert.
+
+## Inhalt des Repositories
+Dieses Repository enthält drei Python-Skripte zur Vorbereitung, Durchführung und Analyse des Mix-Freeze-Vorgangs.
+
+### 1. `artifact.preflight_checker`
+- **Art:** `python_script`
+- **Ziel:** `linux-userspace`
+- **Sprache:** Python
+- **Zweck:** Führt einen Preflight-Check durch, der den Anteil *near-expiry-unpinned* misst und bewertet, ob der Freeze-Status akzeptabel ist.
+
+**API-Funktionen:**
+- **run_preflight_check(valid_runs)** → Liefert ein Dictionary mit den Feldern `freeze_ok`, `freeze_target`, `freeze_tol`.
+
+**Datenstruktur:**
+- `PreflightResult` (JSON): enthält `freeze_ok`, `freeze_target`, `freeze_tol`.
+
+### 2. `artifact.data_logger`
+- **Art:** `python_script`
+- **Ziel:** `linux-userspace`
+- **Sprache:** Python
+- **Zweck:** Loggt relevante Metriken während des Runs basierend auf den Preflight-Ergebnissen.
+
+**API-Funktionen:**
+- **log_metrics(run_id, metrics)** → Protokolliert Lauf-Metriken.
+
+**Datenstruktur:**
+- `Metrics` (JSON): enthält `setup_fingerprint`, `policy_hash`, `epoch_ms`, `near_expiry_unpinned`.
+
+### 3. `artifact.scatter_plot`
+- **Art:** `python_script`
+- **Ziel:** `linux-userspace`
+- **Sprache:** Python
+- **Zweck:** Erstellt eine Scatter-Plot-Visualisierung zur Analyse der Beziehung zwischen `band_width` und `near-expiry-unpinned`.
+
+**API-Funktionen:**
+- **create_scatter_plot(data)** → Erzeugt eine grafische Darstellung der Verhältnisse.
+
+**Datenstruktur:**
+- `ScatterData` (JSON): Felder `band_width`, `near_expiry_unpinned`.
+
+## Installation & Nutzung
+Alle Skripte sind einfache Python-Module für Linux-Nutzungsumgebungen.
+
+### Voraussetzungen
+- Python ≥ 3.8
+- Empfohlene Pakete: `matplotlib`, `pandas`, `numpy`, `json` (Standardbibliothek)
+
+### Generische Installation
+1. Repository klonen:
+   ```bash
+   git clone https://git.donau2space.de/Mika/mix_freeze_analysis
+   cd mix_freeze_analysis
+   ```
+2. Python-Abhängigkeiten installieren:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+### Beispielausführung
+```bash
+python preflight_checker.py
+python data_logger.py
+python scatter_plot.py
+```
+
+## Typische Use-Cases
+- Durchführung eines Preflight-Checks zur Freeze-Prüfung vor AUX-Läufen
+- Laufzeitbasierte Metrik-Erfassung und Analyse
+- Erstellung von Scatter-Plots zur Visualisierung der Metrik-Abhängigkeiten
+
+## Struktur & mögliche Erweiterungen
+- **Preflight-Checker:** Basis für Validierungslogik erweiterbar um zusätzliche Parameterprüfungen.
+- **Data-Logger:** Anbindung an externe Monitoring-Systeme (z. B. Prometheus, InfluxDB) möglich.
+- **Scatter-Plot:** Erweiterung um Heatmaps, Regressionen oder interaktive Dashboards denkbar.
+
+## Lizenz
+Dieses Projekt steht unter der **MIT-Lizenz**.
+
+---
+KI-generierter Inhalt. Verwendung, Änderung und Verbreitung auf eigene Verantwortung.