7757e33a97
Der erste Alltagseinsatz zeigte drei Schoenheitsfehler, alle in der Ausgabe. Der Bericht stand verkehrt herum: Die rsync-Zeilen erschienen VOR "Ziel:" und "Vorpruefung bestanden". Python puffert seine Ausgabe blockweise, sobald sie nicht an ein Terminal geht, waehrend der Unterprozess unmittelbar schreibt. sys.stdout.reconfigure(line_buffering=True) stellt die Reihenfolge her. 150 Zeilen fuer eine uebertragene Datei: --itemize-changes lief auch im echten Durchgang mit, obwohl der Probelauf schon berichtet hatte, was passieren wird. 149 der 150 Zeilen besagten nur ".f..t......" - Inhalt gleich, nur Zeitstempel nachgezogen, die erwartbare Folge von --checksum. Die Auflistung bleibt jetzt dem Probelauf vorbehalten. Der Ersatz war zuerst schlimmer als das Problem: --info=progress2 zeigt am Terminal eine sich selbst ueberschreibende Zeile, in einer Pipe dagegen jeden Zwischenstand einzeln - gemessen 213 Zeilen fuer 213 Dateien. Die Anzeige haengt jetzt an sys.stdout.isatty(). Ausserdem: Die 404-Probe auf anhang-glossar-literatur.html ist entfernt. Die Datei ist geloescht - im Arbeitsbaum, in Git und auf dem Server -, und die Probe koennte einen Rueckschritt gar nicht mehr entdecken: Sie bliebe auch dann gruen, wenn jemand --delete aus dem rsync-Aufruf naehme. Was sie belegt hat, steht in PROGRESS.md. Von vierzehn Adressen bleiben dreizehn. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
228 lines
13 KiB
Markdown
228 lines
13 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: 37 Kapiteldateien + Build-Skripte
|
|
bilder_04/ Quelle: Diagramme + erzeuge_*.py-Generatoren
|
|
web_04/ Quelle: site.css, site.js, icons.svg,
|
|
plotly.min.js, katex/ - die statischen
|
|
Bestandteile der Website
|
|
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 - die EINE Quelle des
|
|
Titeltexts (PDF-Titelseite + Startseite)
|
|
pyproject.toml Quelle: Abhängigkeiten in Gruppen
|
|
Dockerfile, .dockerignore Quelle: Kurs-Image (Programme + JupyterLab)
|
|
LICENSE, LICENSE-TEXT.md MIT fuer Code, CC BY-SA 4.0 fuer den Text
|
|
.gitattributes LF im Repository, egal auf welchem System
|
|
.env.beispiel Vorlage; die echte .env (Ziel des Uploads)
|
|
ist bewusst NICHT im Repository
|
|
pandoc-defaults-basis.yaml, pandoc/, pandoc-defaults-buch.yaml PDF-Konfiguration
|
|
```
|
|
|
|
Nur die als **Quelle** markierten Verzeichnisse werden von Hand bearbeitet. Seit dem
|
|
Umzug nach `web_04/` stimmt dieser Satz auch: Vorher lagen `site.css`, `site.js`,
|
|
`icons.svg` und `katex/` mitten im erzeugten `OR_HTML_04/`. `--check` bewacht das jetzt
|
|
(`pruefe_assets()`), und der Bau bricht ab, wenn jemand die Kopie statt der Quelle
|
|
bearbeitet hat.
|
|
|
|
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
|
|
python3 Operations_Research_mit_Python_Version_04/veroeffentliche_04.py # hochladen
|
|
```
|
|
|
|
`veroeffentliche_04.py` lädt `OR_HTML_04/` per `rsync --delete` nach <https://jamulix.de/OR/>
|
|
— **nicht** per `scp`, denn das überschreibt nur und löscht nie; eine aus dem Buch entfernte
|
|
Seite bliebe sonst dauerhaft online. Vorher prüft es, ob eine Quelldatei neuer ist als die
|
|
gebaute Website (die Website hing einmal wochenlang einen Bau zurück, ohne dass es auffiel),
|
|
hinterher ruft es dreizehn Adressen per HTTP ab. Bei mehr als 30 Löschungen bricht es ab —
|
|
die Liste ist dann anzusehen, bevor `--loeschgrenze N` sie freigibt. Ziel in `.env`
|
|
(nicht im Repository, Vorlage `.env.beispiel`); Anmeldung per SSH-Schlüssel, kein Passwort.
|
|
|
|
`--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 — **zehn** 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, sieben
|
|
„Übung N.N"-Verweise in alter Zählung, die Dateiübersicht des Leser-Wegweisers,
|
|
zuletzt der Titeltext der Startseite).
|
|
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.
|
|
* **Der Titeltext steht in `Kritik_und_Verbesserungsvorschlaege/NEUER_TITEL.md`** und
|
|
nirgends sonst. `titeltexte_04.py` liest ihn; die PDF-Titelseite
|
|
(`bilder_04/erzeuge_titelseite.py`) und der Hero-Block der Startseite
|
|
(`baue_landingpage()`) speisen sich daraus. Eine Titeländerung wird **einmal** dort
|
|
gemacht. Das Vorwort trägt denselben Text als Buchprosa — `pruefe_titeltexte()`
|
|
vergleicht ihn bei jedem `--check` mit der Quelle.
|
|
* **Die Dateiübersicht in `Operations_Research_mit_Python_Version_04/README.md`** steht
|
|
zwischen `<!-- KAPITELTABELLE:ANFANG -->` und `<!-- KAPITELTABELLE:ENDE -->` und wird von
|
|
`schreibe_kapiteltabelle()` aus derselben Struktur erzeugt wie die Nummern im Buch. Nicht
|
|
von Hand bearbeiten — `--check` meldet einen veralteten Block, ein Lauf ohne `--check`
|
|
zieht ihn nach.
|
|
* 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 Kapiteldiagramme, jeweils **aus derselben
|
|
Instanz wie das zugehörige Buchprogramm**. (Das 33. SVG im Verzeichnis ist `titelseite.svg`,
|
|
die der Build bei jedem Lauf selbst schreibt — deshalb nennt `README.md` 33 und diese Datei
|
|
32.) 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 — **beides, sonst trägt das SVG einen
|
|
Zeitstempel und wechselnde `clip-path`-IDs**. Geschrieben wird **nur SVG**; PNG-Zweitfassungen
|
|
gab es einmal, sie wurden nirgends referenziert; 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.
|
|
|
|
---
|
|
|
|
## Veroeffentlichung
|
|
|
|
Das Buch steht online auf <https://jamulix.de/OR/>, das Repository oeffentlich auf
|
|
<https://kitux.de/forgejo/dschlueter/operations_research>.
|
|
|
|
Die Website hat vier Übersichtsseiten: `index.html` (Landing), `programme.html`,
|
|
`notebooks.html` und `stichwortverzeichnis.html`. Die beiden Downloadverzeichnisse
|
|
`programme/` und `Notebooks_04/` bekommen je eine `index.html`, die auf ihre Übersicht
|
|
weiterleitet — sonst antwortet der Webserver mit 403, weil Directory-Listing abgeschaltet
|
|
ist.
|
|
|
|
**Nach jedem `--pdf --html` gehoert `veroeffentliche_04.py` hinterher** — sonst laeuft die
|
|
veroeffentlichte Fassung dem Repository hinterher, und genau das ist einmal wochenlang
|
|
unbemerkt geblieben. Von Hand muss dabei nichts mehr geprueft werden: Das Skript weigert
|
|
sich, einen veralteten Bau hochzuladen, und ruft anschliessend vierzehn Adressen ab.
|
|
|
|
Der erste Lauf am 08.09.2026 uebertrug 213 Dateien und loeschte 35 — 33 verwaiste PNGs, ein
|
|
leeres `__pycache__/` und die geteilte Anhangseite. Alle 35 haette ein `scp`-Upload stehen
|
|
gelassen.
|
|
|
|
**`COLAB_BASIS_URL` ist bewusst leer.** Colab oeffnet Notebooks nur aus GitHub, Google Drive
|
|
oder einem Upload; die URL-Form `colab.research.google.com/github/...` ist fest auf GitHub
|
|
verdrahtet und kann eine selbstgehostete Git-Instanz nicht lesen. Statt eines toten Knopfes
|
|
bekommt jedes Kapitel einen Download-Link auf sein Notebook. Wer spaeter nach GitHub
|
|
spiegelt, traegt dort **einen** Wert ein.
|
|
|
|
Wer ohne eigene Installation rechnen will, nimmt das Kurs-Image:
|
|
`docker run --rm -p 127.0.0.1:8888:8888 or-mit-python` startet JupyterLab mit allen
|
|
25 Notebooks. Ohne Portfreigabe und mit einem Programmnamen als Argument fuehrt dasselbe
|
|
Image ein einzelnes Programm aus.
|
|
|
|
---
|
|
|
|
## Sprache
|
|
|
|
Kommentare, Ausgaben und Fließtext sind durchgängig **Deutsch** — diesen Stil beibehalten.
|