9c83716095
Setzt Paket 5 aus Verbesserungen_02.md um (den Teil, der nicht zurueckgestellt wurde). Fuenf neue Dateien 19_/29_/39_/49_/52_Synthese_*.md, je eine am Ende eines Teils, mit eigener Website-Seite ueber SONDERSEITEN - sie tragen bewusst keine "# Kapitel:"-Ueberschrift, weil sie keine Kapitel sind, sondern der Rueckblick auf einen Teil. Der Entwurf musste sich abgrenzen: Die Teil-Einleitungen haben bereits Entscheidungsdiagramme. Eine zweite Matrix am Teil-Ende waere eine Dopplung gewesen. Die Synthesen leisten deshalb, was eine Einleitung nicht kann - den Vergleich ueber die Kapitel hinweg (Verfahren nebeneinander, mit der Spalte "wo es aufhoert"), eine Tabelle "was dieser Teil gemessen hat" (Behauptung gegen Messung gegen Fundstelle) und drei Fehler, die der Teil verhindert. Zitiert wird ausschliesslich, was im Buch tatsaechlich gerechnet wird. Drei Funde beim Einbau: * Teil III sagte "die drei Kapitel dieses Teils", hat aber fuenf. Phase 3 hatte Mehrziel und Predict-then-Optimize hinzugefuegt, die Einleitung blieb stehen. * 50_Praxis.md verwies auf die Projektwerkstatt mit "acht eigene Anwendungen" - sie hat elf. * Und der eigentliche Fund: Die Lesekette der Quelldateien fuehrte an ACHT Kapiteln vorbei. 12_Python_Oekosystem zeigte direkt auf 20_Lineare_Programmierung, 23_Graphen direkt auf 30_QP, 32_Dynamische direkt auf 40_Finanzdaten, 50_Praxis direkt auf die Projektwerkstatt. Wer der Kette folgte, uebersprang acht von 23 Kapiteln - darunter Metaheuristiken, Spaltengenerierung, Strukturbruecke, Supply-Chain und das ganze Testing-Kapitel. Zehn weitere Dateien hatten gar keine Navigationszeile. Zur Reichweite, damit sie nicht ueberschaetzt wird: Diese Zeilen stehen nur in den Quelldateien. entferne_navigation() streicht sie aus dem Gesamtdokument, und die Website baut ihre Vor/Zurueck-Knoepfe selbst aus DATEIEN. PDF und Website waren nie betroffen - wohl aber jeder, der die Markdown-Dateien im Repository liest, und das wird nach der Veroeffentlichung der Normalfall sein. Die Kette ist jetzt ueber alle 35 Uebergaenge geschlossen, und --check bewacht sie: Fehlt eine Zeile oder zeigt sie an der in DATEIEN folgenden Datei vorbei, ist der Lauf rot. Gegengetestet mit beiden Bruchformen. Stand: 36 Dateien, 296 Abschnitte, 815 Querverweise, 328 Indexmarken, 76 Programme (unveraendert), 33 pytest-Tests, PDF 758 Seiten. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
156 lines
8.3 KiB
Markdown
156 lines
8.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
Kontext zum Repository *Optimierte Entscheidungsfindung mit Python*, Version 04.
|
|
|
|
## Vor jeder Arbeit zuerst lesen
|
|
|
|
* **`PLAN.md`** — das Ziel und der Weg dorthin: alle sechs Phasen, die Zielstruktur, der
|
|
Kapitel-Baukasten, die dreizehn verbindlichen Regeln, die Verifikationsschritte. Ändert
|
|
sich nur bei einem Kurswechsel.
|
|
* **`PROGRESS.md`** — der erreichte Stand: eine Checkliste zur Wiederaufnahme, die
|
|
Referenzwerte zum Gegenprüfen, was erledigt ist, welche Funde es unterwegs gab und **was
|
|
der konkret nächste Schritt ist**. Wird nach jedem Arbeitsschritt fortgeschrieben.
|
|
|
|
Ohne diese beiden Dateien fehlt der Kontext, um sinnvoll weiterzuarbeiten — die Kapiteltexte
|
|
allein verraten weder den Stand noch die Konventionen. Alle sechs Phasen sind abgeschlossen;
|
|
`PROGRESS.md` Abschnitt 7 nennt, was bewusst offen geblieben ist und warum.
|
|
|
|
---
|
|
|
|
## Struktur
|
|
|
|
Dieses Verzeichnis ist die Wurzel; alle Skripte leiten ihre Pfade daraus ab
|
|
(`BASIS = dirname(dirname(__file__))` bzw. `dirname(HIER)`).
|
|
|
|
```
|
|
Operations_Research_mit_Python_Version_04/ Quelle: 36 Kapiteldateien + Build-Skripte
|
|
bilder_04/ Quelle: Diagramme + erzeuge_*.py-Generatoren
|
|
Operations_Research_mit_Python_Version_04.md generiert: Gesamtdokument
|
|
Operations_Research_mit_Python_Version_04.pdf generiert: PDF (xelatex)
|
|
OR_HTML_04/ generiert: Mehrseiten-Website
|
|
Operations_Research_mit_Python_Version_04_Programme/ generiert: Beispielprogramme
|
|
Notebooks_04/ generiert: ein .ipynb je Kapitel
|
|
Kritik_und_Verbesserungsvorschlaege/ Quelle: Rezension, Verbesserungsvorschläge,
|
|
NEUER_TITEL.md (Vorlage des Titelblatts)
|
|
pyproject.toml Quelle: Abhängigkeiten in Gruppen
|
|
pandoc-defaults-basis.yaml, pandoc/, pandoc-defaults-buch.yaml PDF-Konfiguration
|
|
```
|
|
|
|
Nur die als **Quelle** markierten Verzeichnisse werden von Hand bearbeitet.
|
|
|
|
Dieses Verzeichnis ist seit dem 08.09.2026 ein **eigenes Git-Repository** (`main`). Das
|
|
übergeordnete `OR_mit_Python/` ist nur noch das Archiv der Historie bis zur Trennung und
|
|
verwaltet aktiv allein `Version_03`; es trägt `Version_04/` in seiner `.gitignore`. Commits
|
|
gehören ab jetzt hierher.
|
|
|
|
## Build
|
|
|
|
```bash
|
|
cd Version_04
|
|
python3 Operations_Research_mit_Python_Version_04/build_version_04.py --check # nur prüfen
|
|
python3 Operations_Research_mit_Python_Version_04/build_version_04.py --pdf --html
|
|
python3 Operations_Research_mit_Python_Version_04/extract_programme_04.py
|
|
```
|
|
|
|
`--check` prüft mehr als die Struktur: fehlende Codezäune, Links auf nicht existierende
|
|
Dateien und **harte Kapitel-/Abschnitts-/Aufgabennummern im Quelltext**. Es meldet Datei und
|
|
Zeile. Der Suchausdruck erlaubt beliebigen Zwischenraum — der letzte gefundene Fall war ein
|
|
`Handrechnung\n12.1` über zwei Zeilen, an dem jede zeilenweise Suche vorbeiläuft.
|
|
|
|
`build_version_04.py` fasst nicht notwendige harte Zeilenumbrüche innerhalb von Absätzen
|
|
zusammen (`reflow_markdown()`) — viele Markdown-Renderer stellen einen einzelnen Umbruch
|
|
sonst fälschlich als sichtbaren Umbruch dar.
|
|
|
|
---
|
|
|
|
## Die wichtigsten Konventionen
|
|
|
|
**Keine abgeleiteten Zahlen im Quelltext.** Das ist die Regel, an der dieses Projekt am
|
|
häufigsten gescheitert ist — **sieben** Mal an verschiedenen Stellen verletzt gefunden
|
|
(Anhang A, 66 Programm-Docstrings, die Übersichtstabellen der Anhänge, `CLAUDE.md` selbst,
|
|
eine Tabellenzelle, die 98 Lösungsmarken des Anhangs, neun Denkfehler-Verweise).
|
|
Seit dem letzten Fund trägt **keine** Marke mehr eine handgeschriebene Nummer, und `--check`
|
|
bewacht jede Familie. Konkret:
|
|
|
|
* Überschriften: `# Kapitel: <Titel> {#kap:<label>}`, `## Titel {#sec:<label>}` — die Nummer
|
|
vergibt der Build (`resolve_numbering()`, `nummeriere_abschnitte()`).
|
|
* Aufgaben, Handrechnungen, Abbildungen, Micro-Quiz: `**Aufgabe ⭐ — Titel.**`,
|
|
`> **✏️ Handrechnung: Titel**`, ``,
|
|
`> **❓ Micro-Quiz: Titel**` — Nummern von `nummeriere_marken()`.
|
|
* **Lösungen in Anhang A: `**{loesung} — Titel.**`** Der Präfix kommt nicht aus
|
|
`# Anhang A:`, sondern aus dem Kapitel des umgebenden `{#sec:loesungen-<X>}`-Abschnitts —
|
|
die Zuordnung `sec:loesungen-<X>` ↔ `kap:<X>` gilt für alle 23. `--check` zählt zusätzlich
|
|
ab, dass es je Kapitel so viele Lösungen wie Aufgaben gibt.
|
|
* **Der Denkfehler bekommt bewusst gar keine Nummer.** Es gibt je Kapitel genau einen, unter
|
|
einer bereits nummerierten Überschrift. Verwiesen wird auf
|
|
`{ref:sec:<kapitel>-denkfehler}`.
|
|
* Im Fließtext `{ref:<label>}`, nie eine Literalzahl.
|
|
* In Code-Kommentaren und Docstrings der Kapitel**name** („Kapitel Metaheuristiken:"), nie
|
|
die Nummer. Auch nicht im Dateinamen.
|
|
|
|
**Querverweise für die Website** laufen über `baue_seiten_registry()` /
|
|
`resolve_numbering_seite()`, nicht über `resolve_numbering()` — nur dort entsteht aus einem
|
|
seitenübergreifenden Verweis `andere-seite.html#anker`.
|
|
|
|
**Stichwortregister:** `{idx:Begriff}` bzw. `{idx:Oberbegriff!Unterbegriff}`. Vor einem neuen
|
|
Begriff prüfen, ob er schon existiert:
|
|
`grep -ohE '\{idx:[^}]+\}' Operations_Research_mit_Python_Version_04/*.md | sort -u` — sonst
|
|
entstehen zwei Registereinträge für dasselbe Konzept. `texindy` sortiert mit dem deutschen
|
|
`din5007`-Modul (Umlaute wie im Telefonbuch); das generische `-L german` bricht ab.
|
|
|
|
**Programme sind ein Artefakt, keine zweite Quelle.** Änderungen gehören in den
|
|
Kapitel-Codeblock, danach `extract_programme_04.py`. Ein Codeblock gilt als vollständiges
|
|
Programm, wenn er mit `#!/usr/bin/env python3`, einer Leerzeile und `# Name.py` beginnt.
|
|
Auch das `README.md` im Programme-Verzeichnis wird erzeugt — aus der Vorlage
|
|
`README_Programme.md`; `requirements.txt` ist die einzige dort von Hand gepflegte Datei.
|
|
|
|
**`or_kern.py` ist der gemeinsame Unterbau** aller Programme (Domänenmodell, `SolverStatus`,
|
|
`Loesung`-DTO, Abnahmeprüfung). Abgedruckt im Kapitel Praxisfallen.
|
|
|
|
**`ortools` und `highspy` lassen sich nicht im selben Prozess importieren** (beide bringen
|
|
eine eigene HiGHS-Kopie mit). Deshalb lädt `or_kern.py` Solverbibliotheken erst in der
|
|
aufrufenden Funktion, und Programme, die beide brauchen, starten getrennte Prozesse (Muster:
|
|
`Ein_System_Vier_Ansaetze.py`, `Solverwechsel_CPSAT_HiGHS.py`). `cvxpy` zieht ein
|
|
installiertes `highspy` bei der Solver-Erkennung selbst mit hinein — der Konflikt entsteht
|
|
also auch indirekt.
|
|
|
|
**Neue Kapiteldatei** ⇒ in die `DATEIEN`-Liste in `build_version_04.py`.
|
|
**Neues Programm** ⇒ drei Stellen: Kapitelkopf („Programme:"), Vorwort
|
|
(„Verzeichnis der Beispielprogramme"), bei neuer Abhängigkeit `requirements.txt` **und**
|
|
`pyproject.toml` (dort in die passende Gruppe, nicht pauschal in die Grundausstattung).
|
|
|
|
Die vollständigen **dreizehn Regeln** stehen in `PLAN.md` Abschnitt 9 — darunter, dass jede
|
|
abgedruckte Ausgabe aus einem echten Lauf stammt und dass `PROGRESS.md` in denselben Commit
|
|
gehört wie die Arbeit, die sie beschreibt.
|
|
|
|
---
|
|
|
|
## Diagramme
|
|
|
|
`bilder_04/erzeuge_*.py` erzeugen 18 der 32 SVGs, jeweils **aus derselben Instanz wie das
|
|
zugehörige Buchprogramm**. Das ist kein Selbstzweck: Von zehn nachgebauten Bildern förderten
|
|
sieben einen Fehler zutage — dreimal ein Modell, das im Buch gar nicht vorkommt, einmal
|
|
widersprüchliche Zahlen zwischen Bild und Text, einmal ein gekipptes Vorzeichen. Wer ein
|
|
Diagramm anfasst, vergleicht es zuerst mit dem Modell des Kapitels.
|
|
|
|
Die übrigen 14 sind schematisch (Kästen, Pfeile, beschriftete Formeln) und bekommen bewusst
|
|
keinen Generator — dort kann nichts driften. Das Kriterium steht in `PROGRESS.md`
|
|
Abschnitt 6c.
|
|
|
|
Konventionen der Generatoren: `plt.rcParams["svg.hashsalt"] = "or-mit-python-v04"` und
|
|
`metadata={"Date": None}` für byteidentische Läufe; stammt die Instanz aus einem
|
|
Zufallsstrom, wird die Ziehungsreihenfolge des Buchprogramms nachgespielt.
|
|
|
|
## Plotly-Figuren
|
|
|
|
`{plotly:name}` bindet `bilder_04/plotly/<name>.html` in die Kapitelseite ein. Das Fragment
|
|
wird als Rohblock ` ```{=html} ` ausgegeben — **nicht** als blankes HTML: Plotlys Fragment ist
|
|
eine einzige lange Zeile mit eingebetteten Leerzeichenketten, aus der Pandoc sonst einen
|
|
Codeblock macht. Genau daran waren alle vier Figuren kaputt, bis es die Schlussabnahme fand.
|
|
Im PDF steht stattdessen ein Hinweis auf die Website.
|
|
|
|
---
|
|
|
|
## Sprache
|
|
|
|
Kommentare, Ausgaben und Fließtext sind durchgängig **Deutsch** — diesen Stil beibehalten.
|