# PLAN — Optimierte Entscheidungsfindung mit Python, Version 04 **Zweck dieser Datei:** Sie hält den *vollständigen* Umbauplan von Version 03 zu Version 04 fest, mit allen Phasen, Konventionen und Prüfschritten — unabhängig davon, wie weit die Arbeit gediehen ist. Was davon bereits erledigt ist, steht in **[PROGRESS.md](PROGRESS.md)**. > **Arbeitsteilung der beiden Planungsdateien** > > | Datei | Inhalt | ändert sich | > | --- | --- | --- | > | `PLAN.md` (diese Datei) | das Ziel und der Weg dorthin | selten — nur bei Kurswechsel | > | `PROGRESS.md` | der erreichte Stand, mit Zahlen und Funden | nach jedem Arbeitsschritt | > > Beide liegen im **Repo-Wurzelverzeichnis**, nicht im Kapitelverzeichnis: Sie regieren > sechs Verzeichnisse, nicht nur die Kapitelquellen, und stehen dort neben `CLAUDE.md`, das > als einzige Datei von jeder neuen Sitzung automatisch gelesen wird und auf sie verweist. > > Die frühere `Operations_Research_mit_Python_Version_04/ARBEITSPLAN.md` ist am > 7. September 2026 in diesen beiden Dateien aufgegangen und wurde gelöscht (Commit-Historie > bewahrt sie auf). Eine Sache an zwei Stellen zu pflegen ist genau der Fehler, an dem in > diesem Projekt schon einmal Buch und Programme-Verzeichnis auseinandergelaufen sind. **Stand des Plans:** 7. September 2026 · Branch `main` · Version 03 bleibt unangetastet und weiter baubar; Version 04 ist ein paralleler Strang. --- ## 1. Warum es Version 04 gibt Grundlage ist die Rezension in `Kritik_und_Verbesserungsvorschlaege/Kritik.md`. Sie benennt drei Schwächen von Version 03: 1. den steilen thematischen Bruch zwischen Logistik (Teil II/III) und Finanzmärkten (Teil IV), 2. die hohe mathematische und architektonische Einstiegshürde, 3. die Lücke bei Metaheuristiken und nicht-konvexer Optimierung. Version 03 ist ein fachlich starkes, aber akademisch getaktetes Kompendium (22 Dateien, ~13 650 Zeilen, 42 Beispielprogramme). Version 04 baut es vom **Nachschlagewerk zum Kursbegleiter** um: Die Teilnehmer sollen schnelle, messbare Erfolge erleben und die Verfahren am nächsten Arbeitstag anwenden können. ### Die drei Leitprinzipien 1. **Time-to-First-Success minimieren** — ein lauffähiges Aha-Erlebnis *vor* der formalen Theorie. 2. **Kognitive Entlastung** — Formeln konsequent in Klartext, Alltagssprache und Geometrie übersetzen. 3. **Robuste Praxistauglichkeit** — Typsicherheit, echte Datenpipelines, ehrliches Debugging statt idealisierter Beispiele. ### Getroffene Grundsatzentscheidungen | Frage | Entscheidung | | --- | --- | | Bilder | eigenes `bilder_04/`, damit V03 eingefroren bleibt | | Fremdbibliotheken | polars, pyomo, linopy, pymoo, celery, cvxpylayers **installiert** — die Programme laufen wirklich. Ipopt/CyIpopt und Redis/Docker bleiben illustrativ mit dokumentiertem Fallback | | Notebooks | lokal in `Notebooks_04/`, Colab-Link aus **einer** Konstanten `COLAB_BASIS_URL` in `build_version_04.py` | | Plotly | zweigleisig: Matplotlib/Graphviz bleibt PDF-Quelle, Plotly zusätzlich in die Website eingebettet | | Nicht ausführbare Inhalte | ausdrücklich als solche kennzeichnen (z. B. MINLP/Ipopt) statt Ausgaben zu erfinden | --- ## 2. Zielstruktur 22 → 29 Textdateien. Neue Kapitel **fett**. Kapitelnummern entstehen automatisch aus `{#kap:label}`, Querverweise laufen über `{ref:...}`, Abschnittsnummern vergibt der Build — Einfügen ist daher an keiner Stelle mit Handarbeit verbunden. | Teil | Kapitel | | --- | --- | | I Grundlagen | 1 Einführung · 2 Fundament · 3 Python-Ökosystem · **4 Vom Management-Wunsch zum Modell** | | II Kernverfahren | *Entscheidungs-Flussdiagramm* · 5 LP · 6 MILP · 7 CP-SAT · 8 Graphen/Touren · **9 Metaheuristiken** | | III Nichtlinearität/Unsicherheit | *Entscheidungs-Flussdiagramm* · 10 QP/NLP/MINLP · 11 Unsicherheit · 12 Dynamische Programmierung · **13 Mehrziel & Pareto** | | IV Brücke & Vertiefung | **14 Strukturbrücke Logistik ↔ Finance** · **15 Predict-then-Optimize** · **16 Supply-Chain & Energieeinsatz unter Unsicherheit** | | V Finanzmärkte (Vertiefung) | 17 Finanzdaten · 18 Markowitz · 19 CVaR · 20 Handelsmaschine | | VI Praxis | 21 Praxisfallen · **22 Testing, Benchmarking, Deployment** · Projektwerkstatt | | Anhänge | A Lösungen · B Modellierungsmuster · C Fehlerdiagnose & IIS · **D Spickzettel** · E Glossar/Literatur | Teil V (Finanzmärkte) wird im Vorwort und im Teil-Auftakt ausdrücklich als **spezialisierte Vertiefungsdomäne** gekennzeichnet; Kapitel 16 ist die gleichwertige Nicht-Finanz-Alternative mit denselben Werkzeugen. ### Verzeichnisse ``` Operations_Research_mit_Python_Version_04/ Quelle: Kapiteldateien + Build-Skripte Operations_Research_mit_Python_Version_04_Programme/ generiert: Beispielprogramme Notebooks_04/ generiert: ein .ipynb je Kapitel bilder_04/ Quelle: Diagramme + Generatorskripte OR_HTML_04/ generiert: Mehrseiten-Website Operations_Research_mit_Python_Version_04.md / .pdf generiert ``` --- ## 3. Phase 0 — Infrastruktur *Voraussetzung für alles Weitere; wird zuerst und vollständig abgeschlossen.* **`build_version_04.py`** — Fork von `build_version_03.py` mit vier Eingriffen; alles andere bleibt identisch: 1. **Pfadkonstanten zentralisieren.** Ein Versionsblock am Dateikopf: `ZIEL_MD`, `PDF_DATEINAME`, `PROGRAMME_VERZ`, `BUILD_BASISNAME`, `BILDER_NAME/VERZ`, `HTML_NAME/VERZ`, `NOTEBOOK_NAME/VERZ`, `COLAB_BASIS_URL`. 2. **Bildpfade.** V04-Markdown referenziert `bilder_04/…`. Fürs PDF löst Pandoc relativ zum Repo-Wurzelverzeichnis auf; für die Website spiegelt `spiegle_bilder()` das Verzeichnis nach `OR_HTML_04/`. 3. **Automatische Abschnittsnummerierung.** `nummeriere_abschnitte()` vergibt `## 5.4 Titel` (im Anhang `## C.4 Titel`) beim Bauen; `ABSCHNITT_RE` erwartet im Quelltext **keine** Nummer mehr. Analog in `baue_seiten_registry()` / `resolve_numbering_seite()`. **Ohne diesen Eingriff zöge jedes eingefügte Kapitel Handarbeit in allen Folgekapiteln nach sich.** 4. **Neue Bausteine.** `resolve_plotly()` + `kopiere_plotly_bibliothek()` (Plotly-Fragmente in die Kapitelseiten einbetten, im PDF statischer Ersatz), `baue_notebooks()` + `ergaenze_notebook_hinweis()` + `spiegle_notebooks()`, erweitertes `markiere_karten()` für die neuen Kartentypen, `KEINE_KAPITELDATEIEN`. **`extract_programme_04.py`** — Fork von `extract_programme.py`, nur `ZIEL_DIR`/`HIER` und die README-Vorlage umgestellt. Extraktionsmuster (`#!/usr/bin/env python3`, Leerzeile, `# Name.py`) bleibt unverändert. **`OR_HTML_04/assets/site.css`** — neue Boxklassen für 5-Minuten-Box, Formel-Übersetzer, Excel-Brücke, Micro-Quiz und Denkfehler-Aufgabe. **Abschluss:** `--check`, `--pdf` und `--html` laufen mit inhaltlich unverändertem V03-Text sauber durch. Erst dann beginnt inhaltliche Arbeit. --- ## 4. Phase 1 — Didaktik-Layer über alle bestehenden Kapitel Pro Kapitel, in Lesereihenfolge, jeweils dieselben Bausteine (siehe Abschnitt 8): * **„In 5 Minuten gelöst“** als erster Abschnitt: 4–6 Zeilen Daten, ≤ 15 Zeilen Code, betriebswirtschaftlich sofort lesbares Ergebnis — danach erst „Warum funktioniert das?“. * **Formel-Übersetzer-Tabellen** (zweispaltig Mathematik | Alltagssprache) an jeder zentralen Formel; die bestehenden „Lesehilfe“-Blöcke gehen darin auf. * **Micro-Quiz** (genau 3 Multiple-Choice-Fragen) und **„Finde den Denkfehler“** (lauffähiger Code mit betriebswirtschaftlich unsinnigem Ergebnis: `>=` statt `<=`, vergessene Ganzzahligkeit, Big-M zu klein, Zirkelbezug) je Kapitelende; Lösungen nach Anhang A. * **Notebook-Badge** im „Kapitel auf einen Blick“-Block. ### Kapitelspezifische Ergänzungen | Kapitel | Ergänzung | | --- | --- | | 1 Einführung | **Excel-zu-Python-Brücke:** Excel-Solver-Modell Zelle für Zelle übersetzt, `pandas.read_excel()` → Modell → formatierter Export | | 2 Fundament | **Numerik-Deep-Dive:** Konditionszahl $\kappa(A)$ als Experiment (Kosten $10^7$ gegen Toleranzen $10^{-6}$ → falsches `INFEASIBLE`), Ruiz-Equilibrierung, Geometrie vor Algebra | | 3 Ökosystem | Pyomo/Linopy im Vergleich zu CVXPY/OR-Tools; vektorisierte Modellgenerierung (NumPy, Polars) gegen `for`-Schleifen gebenchmarkt; wiederverwendbare Excel-/CSV-Pipeline | | 4 LP | Primal-/Dual-/Integralitätstoleranzen, Degeneriertheit als Vorschau auf Anhang C | | 5 MILP | MIP-Gap, Time-Limit, Warm-Starts (`SetHint`/`highspy`), warum `0.99999998` nicht `int()` verträgt | | 6 CP-SAT | vollständige Statusauswertung, interaktives Gantt (Plotly) | | Teil-Auftakte II und III | Entscheidungs-Flussdiagramm „Welcher Solver passt zu meinem Problem?“ (Graphviz) | --- ## 5. Phase 2 — Code-Architektur auf Enterprise-Niveau Neues gemeinsames Modul **`or_kern.py`** im Programme-Verzeichnis (folgt dem Extraktionsmuster, wird also mitgeneriert) — der greifbare Beleg für Clean Architecture: ``` Rohdaten (Excel/CSV) → Domänenmodell (Pydantic, geprüft) → Modellbauer (solverabhängig) → Lösung (DTO, solverunabhängig) → Abnahmeprüfung ``` * **Pydantic-v2-Basismodelle** für Ressourcen, Bedarfe, Kosten- und Renditematrizen mit Validierung beim Einlesen (strikt positive Kapazitäten, Wahrscheinlichkeiten summieren auf 1, Spaltenzuordnung über Namen statt Positionen). * **Einheitliches `Loesung`-DTO** plus `SolverStatus`-Enum (`OPTIMAL`, `ZULAESSIG`, `UNZULAESSIG`, `UNBESCHRAENKT`, `ZEITLIMIT`, `FEHLERHAFT`, `UNBEKANNT`) mit Übersetzern für pywraplp, CP-SAT, highspy, SciPy und CVXPY. **Lazy imports**, weil `ortools` und `highspy` sich nicht gemeinsam importieren lassen. * **Excel-/CSV-Ein- und -Ausgabe** (`lade_produktionsproblem()`, `schreibe_ergebnis()`), pandas als optionale Abhängigkeit. Alle bestehenden Programme werden darauf umgestellt: durchgängige Type Hints (mypy-kompatibel), Domäne strikt vom Solver getrennt, keine impliziten Optimalitätsannahmen mehr. Der **Solver-Austausch HiGHS ↔ CP-SAT** wird an einem Beispiel real vorgeführt. > **Maßstab bei jeder Umstellung:** Wird das Programm dadurch kürzer *und* klarer? Wenn > nicht, bleibt es. Ein Lehrbeispiel darf nicht an Architektur ersticken — das gilt > besonders für die frühen Kapitel, wo die Leser das Modul noch nicht kennen. --- ## 6. Phase 3 — Neue Kapitel * **Kap. 4 Vom Management-Wunsch zum Modell** — Anforderungsanalyse für OR-Projekte, realistischer Dialog („Kosten senken, aber die Mitarbeiter sollen nicht meckern“), systematische Zerlegung in Entscheidungsvariablen / harte vs. weiche Restriktionen (Strafkosten) / fehlanreizfreie Zielfunktion. * **Kap. 9 Metaheuristiken** — wenn HiGHS/CP-SAT skalierungsbedingt aussteigen: lokale Suche mit Kostenänderung in $O(1)$, Simulated Annealing samt Kalibrierung der Temperatur, der gemessene Umschlagpunkt gegen den exakten Solver, Large Neighborhood Search (zerstören / exakt reparieren). **Dekomposition wurde aus diesem Kapitel herausgenommen** und ist ein eigener offener Punkt: Spaltengenerierung gibt eine *andere* Antwort auf dieselbe Frage — sie approximiert nicht die Lösung, sondern formuliert das Modell um. Genetische Algorithmen (`pymoo`) und Tabu-Suche sind im Kapitel benannt und eingeordnet, aber nicht ausgeführt: Für Reihenfolgen ist die „Kreuzung“ zweier Lösungen gerade der schwierige Teil, und ein halbherziges Beispiel dazu wäre irreführend. * **Kap. 13 Mehrziel & Pareto** — warum lineare Skalarisierung bei nicht-konvexen Fronten versagt; $\epsilon$-Constraint und lexikografische Optimierung an Kosten vs. CO₂ in der Tourenplanung; exakte Pareto-Front, statisch fürs PDF und interaktiv (Plotly) auf der Website. * **Kap. 14 Strukturbrücke** — dieselbe Mathematik, zwei Welten: Ressourcenallokation ↔ Kapitalallokation, Lieferausfall-Robustheit ↔ Worst-Case-Risikomaße; Gegenüberstellung als Tabelle plus ein Modell, das beide Datensätze frisst. * **Kap. 15 Predict-then-Optimize** — Nachfrageprognose → Lagerbestand: ein Modell mit kleinerem MSE erzeugt teurere Entscheidungen; Entscheidungskosten statt Prognosefehler messen; Ausblick `cvxpylayers`/PyTorch. * **Kap. 16 Supply-Chain & Energieeinsatz unter Unsicherheit** — die Nicht-Finanz-Alternative zu Teil V mit denselben Werkzeugen (Szenarien, CVaR, DP): Netzwerkdesign mit Standortentscheidungen, Kraftwerkseinsatzplanung. * **Kap. 22 Testing, Benchmarking, Deployment** — pytest-Framework für Optimierungsmodelle (Regression gegen Benchmark-Instanzen, Restriktionsverletzungs-Checks, Skalierungsinvarianz), reproduzierbare Benchmark-Pipeline SciPy/HiGHS/OR-Tools/CVXPY über $N \in \{10^2, 10^3, 10^4\}$ (Zeit und Speicher), FastAPI-Microservice mit asynchroner Job-Queue und schlankem `Dockerfile`. ### Empfohlene Reihenfolge Nicht strikt nach Kapitelnummer, sondern nach Nutzen — falls vor einem Kurstermin ein brauchbarer Zwischenstand gebraucht wird: 1. **Kap. 9 Metaheuristiken** — schließt die von der Rezension am schärfsten benannte Lücke. 2. **Kap. 22 Testing/Deployment** — zweite große Lücke; der Unterbau (`or_kern.py`) steht bereits und ist genau das, was sich testen lässt. 3. **Kap. 4 Vom Management-Wunsch zum Modell** — kurz, didaktisch tragend, ohne neue Bibliotheken. 4. **Kap. 13 Mehrziel**, **Kap. 14 Strukturbrücke**, **Kap. 15 Predict-then-Optimize**. 5. **Kap. 16 Supply-Chain & Energie** — die aufwendigste Einheit und am ehesten verzichtbar, falls der Umfang begrenzt werden muss. --- ## 7. Phase 4 — Anhänge · Phase 5 — Medien, Rahmen, Gesamtbau ### Phase 4 — Anhänge * **Anhang C → vollwertiges Troubleshooting-Handbuch:** IIS/Conflict Refiner in Python (deletion filter, der aus tausenden Restriktionen die minimale widersprüchliche Teilmenge isoliert), duale Entartung und instabile Schattenpreise, Toleranzkunde (`feasibility_tolerance` HiGHS vs. OR-Tools), Skalierung/Ruiz. * **Anhang D (neu) Spickzettel** — je eine Seite SciPy, HiGHS, CP-SAT, CVXPY, Pyomo/Linopy: Variablentypen, Big-M-Entweder-Oder, weiche Restriktionen mit Slack, Dualwerte und Status abfragen. * **Anhang B** — Rezeptkarten für Alltagsfragen (Mindestabnahmemengen, Rüstzeiten, Budgetlimit), abgestimmt auf Anhang D. * **Anhang A** — Lösungen für alle neuen Aufgaben, Micro-Quizzes und Denkfehler-Übungen; läuft parallel zu jeder Phase mit. ### Phase 5 — Medien, Rahmen, Gesamtbau * **Diagramme** in `bilder_04/`: zwei Entscheidungs-Flussdiagramme, Branch-and-Bound-Baum, Pareto-Front, Konditionszahl-Experiment, Metaheuristik-Landschaft, Clean-Architecture-Schichten, FastAPI-Deployment — Graphviz bzw. Matplotlib, jeweils SVG + PNG. **Diesmal mit mitgelieferten Generatorskripten** (`bilder_04/erzeuge_*.py`); in V03 fehlen die Diagrammquellen. * **Plotly-Figuren** nach `bilder_04/plotly/*.html`, vom Build in die Kapitelseiten eingebettet; im PDF steht die statische Variante. * **Notebooks** je Kapitel nach `Notebooks_04/`, aus den Kapitel-Codeblöcken generiert, mit `pip install`-Startzelle. * **Rahmen aktualisieren:** Vorwort (Lernpfade um die neuen Kapitel und den Finanz-/Industrie-Gabelpunkt erweitert), Notation, Projektwerkstatt (Projekte zu Metaheuristik, Mehrziel und Deployment), Programme-README-Vorlage, `requirements.txt`, `CLAUDE.md` um den V04-Strang ergänzt. * **Abschluss:** vollständiger Bau von Markdown, PDF und Website. --- ## 8. Der Kapitel-Baukasten Jedes Kapitel der Version 04 erhält dieselben Bausteine in derselben Reihenfolge: ``` # Kapitel: {#kap: