operations_research/README.md

# Optimierte Entscheidungsfindung mit Python — Version 04

Quellen, Build-Werkzeuge und Ausgaben des Lehrbuchs *Optimierte Entscheidungsfindung mit Python*
(Autor: Dieter Schlüter). Dieses Verzeichnis ist die Wurzel: Alle Skripte leiten ihre Pfade
daraus ab, und alle Befehle unten werden **hier** ausgeführt.

> Dies ist die Bau-Anleitung für das Repository. Der Wegweiser **für Leserinnen und Leser des
> Buchs** — Aufbau, Lernpfade, Voraussetzungen — steht in
> [`Operations_Research_mit_Python_Version_04/README.md`](Operations_Research_mit_Python_Version_04/README.md).

---

## Was hier liegt

| Pfad | Rolle |
| --- | --- |
| `Operations_Research_mit_Python_Version_04/` | **Quelle**: 36 Kapiteldateien (inkl. 5 Teil-Synthesen) + Build-Skripte |
| `bilder_04/` | **Quelle**: Diagramme (SVG/PNG) + `erzeuge_*.py`-Generatoren |
| `Operations_Research_mit_Python_Version_04.md` | generiert: Gesamtdokument (Pandoc-Eingabe) |
| `Operations_Research_mit_Python_Version_04.pdf` | generiert: PDF, 760 Seiten |
| `OR_HTML_04/` | generiert: **Mehrseiten-Website** — dieser Ordner wird veröffentlicht |
| `Operations_Research_mit_Python_Version_04_Programme/` | generiert: 76 lauffähige Beispielprogramme |
| `Notebooks_04/` | generiert: ein Jupyter-Notebook je Kapitel |
| `PLAN.md` / `PROGRESS.md` | das Ziel des Umbaus und der erreichte Stand |
| `pyproject.toml` | Abhängigkeiten in Gruppen (`finance`, `large-scale`, `api`, …) |
| `Dockerfile`, `.dockerignore` | zweistufiges Kurs-Image (führt die Programme aus, baut nicht das Buch) |
| `pandoc-defaults-*.yaml`, `pandoc/` | Konfiguration des PDF-Baus |

**Nur die als *Quelle* markierten Verzeichnisse werden von Hand bearbeitet.** Alles andere
wird erzeugt und bei jeder inhaltlichen Änderung neu gebaut — insbesondere gehören
Programmänderungen in den Kapitel-Codeblock, nicht in das Programme-Verzeichnis.

---

## Bauen

```bash
cd Version_04

# nur prüfen: Struktur, Querverweise, Codezäune, harte Nummern
python3 Operations_Research_mit_Python_Version_04/build_version_04.py --check

# Gesamtdokument, PDF und Website
python3 Operations_Research_mit_Python_Version_04/build_version_04.py --pdf --html

# Beispielprogramme aus den Kapiteln extrahieren
python3 Operations_Research_mit_Python_Version_04/extract_programme_04.py
```

Die Website ist danach in `OR_HTML_04/` vollständig und **selbstgenügsam** — alle Verweise
zeigen auf Unterverzeichnisse (`assets/`, `bilder_04/`, `katex/`, `Notebooks_04/`). Der Ordner
lässt sich unverändert auf einen Webserver kopieren.

---

## Voraussetzungen

**Python-Pakete** — alles auf einen Schlag, wie im Buch abgedruckt
([`requirements.txt`](Operations_Research_mit_Python_Version_04_Programme/requirements.txt)):

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r Operations_Research_mit_Python_Version_04_Programme/requirements.txt
```

Wer eine schlanke Umgebung möchte, nimmt stattdessen [`pyproject.toml`](pyproject.toml) mit
seinen Gruppen — die Grundausstattung trägt den Großteil des Buchs:

```bash
pip install -e .                  # numpy, scipy, pandas, matplotlib, openpyxl, pydantic, ortools, cvxpy
pip install -e ".[finance]"       # scikit-learn, yfinance
pip install -e ".[large-scale]"   # highspy, Pyomo, linopy, polars
pip install -e ".[api]"           # fastapi, uvicorn, httpx
pip install -e ".[figures]"       # plotly, graphviz — nur zum Neuerzeugen der Diagramme
pip install -e ".[dev]"           # pytest
```

**`ortools` steht in der Grundausstattung, `highspy` erst in `[large-scale]`.** Das ist
Absicht: Beide bringen eine eigene HiGHS-Kopie mit und vertragen sich nicht im selben
Prozess. Wer die Grundausstattung installiert, kann in den Konflikt gar nicht geraten —
`cvxpy` zieht `highspy` **nicht** nach, erkennt es aber, sobald `[large-scale]` es
mitgebracht hat.

`graphviz` fehlt in der `requirements.txt` — es wird allein von
`bilder_04/erzeuge_architektur_diagramme.py` gebraucht, nicht von den Beispielprogrammen,
und steht darum nur in `[figures]`.

### Oder im Container

Wer nichts installieren will, baut das Kurs-Image:

```bash
docker build -t or-mit-python .
docker run --rm or-mit-python Installationstest.py
docker run --rm or-mit-python Rucksack.py
docker run --rm -it or-mit-python                        # Python-Eingabe
docker run --rm -v "$PWD/ausgabe:/buch/output" or-mit-python Excel_Bruecke.py
```

Zweistufiger Bau: Die erste Stufe übersetzt die Abhängigkeiten in eine virtuelle Umgebung
und braucht dafür einen Compiler, die zweite kopiert nur das Ergebnis — die Bauumgebung
landet nicht im Image. Enthalten sind die Gruppen `finance`, `large-scale`, `api` und `dev`;
`figures` fehlt bewusst, weil es zusätzlich Graphviz verlangt und nur dem Neuerzeugen der
Diagramme dient.

**Das Image führt die Programme aus, es baut das Buch nicht.** Für PDF und Website braucht
es pandoc, xelatex und inkscape — zusammen über ein Gigabyte, ohne Nutzen für jemanden, der
die Beispiele durchrechnen will.

Zwei Punkte, die nicht offensichtlich sind: Das Image enthält `ortools` **und** `highspy`,
obwohl sie sich nicht gemeinsam importieren lassen — der Konflikt wird zur Laufzeit durch
getrennte Prozesse gelöst, nicht durch Weglassen. Und `libgomp1` muss im schlanken
Basis-Image nachinstalliert werden, sonst scheitert der erste Solveraufruf mit
`libgomp.so.1: cannot open shared object file`.

**Externe Werkzeuge**, je nachdem, was gebaut werden soll:

| Werkzeug | wofür | ohne es |
| --- | --- | --- |
| `pandoc` (≥ 3.0) | PDF und Website | `--pdf`/`--html` scheitern; `--check` läuft |
| `xelatex` + `texindy` | PDF | kein PDF; Website unberührt |
| `inkscape` | SVG-Grafiken im PDF | LaTeX bricht bei `\includesvg` ab |
| `dot` (Graphviz) | 5 der 15 Bildgeneratoren | nur beim Neuerzeugen dieser Diagramme nötig |

**`OR_HTML_04/katex/`** ist externes Material und wird von keinem Skript erzeugt. Fehlt es,
bleiben die Formeln auf der Website ungesetzt.

---

## Zwei Werte, die beim Veröffentlichen zu setzen sind

1. **`COLAB_BASIS_URL`** in `Operations_Research_mit_Python_Version_04/build_version_04.py`.
   Sie trägt Kontoname und Repository-Name; die 25 Colab-Badges auf den Kapitelseiten hängen
   daran. Der Pfadteil `Notebooks_04/…` wird relativ zur Repository-Wurzel aufgelöst und
   stimmt bereits. Ein Leerstring schaltet die Badges ab.
2. Nichts weiter. Alle übrigen Pfade sind relativ.

---

## Warum die PDF-Konfiguration doppelt vorliegt

`pandoc-defaults-basis.yaml` ist eine Kopie der Benutzerdatei
`~/.config/pandoc/defaults.yaml` (Schriften, Geometrie, Seitenlayout) — mit **relativem**
Pfad auf `pandoc/header-includes.tex` statt des absoluten, der dort steht. Ohne diese Kopie
könnte ein frischer Klon kein PDF bauen. `build_version_04.py` bevorzugt sie und fällt auf
die Benutzerdatei zurück, falls sie fehlt.

`pandoc-defaults-buch.yaml` enthält die projektspezifischen Überschreibungen
(Inhaltsverzeichnis und Nummerierung werden im Markdown selbst erzeugt, `-shell-escape` für
`\includesvg`). Die eigentliche Buchtypografie steht in `bilder_04/or_pdf_header.tex`.

---

## Verlauf

Version 04 baut das Werk vom Nachschlagewerk zum Kursbegleiter um; alle sechs Phasen sind
abgeschlossen. **Was geplant war, steht in [`PLAN.md`](PLAN.md); was erreicht ist und woran
man das nachprüft, in [`PROGRESS.md`](PROGRESS.md)** — einschließlich der Funde unterwegs und
der Regeln, die sich daraus ergeben haben. Wer hier weiterarbeitet, liest beide zuerst.