nicolai/LEAG-COALLOG
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
LEAG-COALLOG/AGENTS.md
Nicolai 4bf7d47007 unnötige variablen rausgelöscht
2026-04-24 11:32:38 +02:00

7.4 KiB
Raw Blame History

in Agents.md steht alles drin, was du brauchst# AGENTS.md

Projektkontext

LEAG-COALLOG ist ein Proof of Concept zur Optimierung der Braunkohle-Logistik. Das System verarbeitet eine Excel-Parameterdatei, erzeugt daraus normalisierte Parquet-Tabellen und loest anschliessend ein Pyomo-Optimierungsmodell fuer Lieferungen von Tagebauen zu Kraftwerken und Veredlung.

Ziel ist eine planbare Rohkohleverteilung unter Beruecksichtigung von Nachfrage, Toleranzen, Mischungsverhaeltnissen, Foerder- und Verladungskapazitaeten, Verfuegbarkeiten, Schichtmustern, Bunkerlogik und Solver-Limits. Die Webapp dient als Bedienoberflaeche fuer Upload, Parametrisierung, Laufstatus, Logs, Visualisierung und Ergebnisdownload.

Architektur

Die Anwendung besteht aus drei Hauptteilen:

  1. Preprocessing

    • Datei: src/preprocessing/exploration_preprocess.py
    • Liest die Excel-Datei aus POC1_INPUT_XLSX.
    • Schreibt vorbereitete Tabellen als Parquet nach POC1_OUTPUT_DIR.
    • Die Logik stammt aus einem Notebook-Export und ist stark an die Struktur der Eingabe-Excel gebunden.

  2. Optimierung

    • Einstieg: src/optimization/run_optimization.py
    • Modell: src/optimization/model_builder.py
    • Laedt alle Parquet-Dateien aus einem Datenverzeichnis.
    • Baut ein Pyomo ConcreteModel.
    • Loest mit highs, gurobi oder scip.
    • Exportiert output.xlsx und optional warmstart.json.

  3. Webapp

    • Backend: webapp/backend/main.py
    • Frontend: webapp/frontend/src/App.jsx
    • FastAPI nimmt Uploads entgegen, legt Job-Verzeichnisse unter var/jobs an und startet Preprocessing und Optimierung als Subprozesse.
    • React/Vite stellt Upload, Solver-Parameter, Job-Status, Logs, Plots, Warmstart und Downloads bereit.

Datenfluss

Standardablauf eines Webapp-Laufs:

  1. Browser sendet Excel-Datei, Solver und Parameter an POST /api/run.
  2. FastAPI erstellt ein Job-Verzeichnis unter var/jobs/<job_id>/.
  3. Die Upload-Datei wird als input.xlsx gespeichert.
  4. exploration_preprocess.py schreibt processed/*.parquet.
  5. run_optimization.py liest processed/*.parquet, baut und loest das Modell.
  6. Ergebnisse landen in output/output.xlsx und output/warmstart.json.
  7. Logs liegen unter logs/preprocess.log und logs/optimization.log.
  8. Das Frontend pollt Status, Logs und abgeleitete Visualisierungsdaten.

Wichtige API-Endpunkte:

  • GET /api/health
  • POST /api/run
  • GET /api/jobs/{job_id}
  • POST /api/jobs/{job_id}/cancel
  • GET /api/jobs/{job_id}/output
  • GET /api/jobs/{job_id}/warmstart
  • GET /api/jobs/{job_id}/monthly-flows
  • GET /api/jobs/{job_id}/capacity-timeseries
  • GET /api/jobs/{job_id}/logs/{log_name}
  • GET /api/jobs/{job_id}/logs/{log_name}/stream

Optimierungsmodell

Das Modell bildet Liefermengen als ganzzahlige Schritte ab:

  • Quellen I: Reichwalde, Nochten, Welzow
  • Ziele J: J, SP, B3, B4, V
  • Tage D: Bergbauwoche Samstag bis Freitag
  • Schichten S: F, S, N
  • Entscheidung k[i,j,w,d,s]: ganzzahlige Anzahl Lieferschritte
  • Fluss x[i,j,w,d,s] = step_size_tonnes * k[i,j,w,d,s]

Wichtige Nebenbedingungen und Konzepte:

  • Tages-, Wochen- und Monatstoleranzen fuer Kraftwerke
  • separate Veredlungsbedarfe fuer Nochten- und Welzower-Kohle
  • harte Mix-Min/Max-Grenzen und weiche Zielabweichungen
  • Foerderkapazitaeten pro Monat
  • Verladungskapazitaeten pro Schicht und Tag
  • Verfuegbarkeiten aus Verfuegbarkeiten.parquet
  • feste Routenverbote und kombinierte Flussgrenzen
  • Schichtglaettung und Schichtmuster
  • optionale Bunkerlogik fuer Ziele mit Bunkerparametern
  • Warmstart Import/Export fuer Folgelaeufe

Weitere fachliche Details stehen in:

  • README.md
  • docs/app-kommunikation.md
  • notebooks/constraints_overview.md
  • latex/modellierung.tex

Wichtige Verzeichnisse

  • src/preprocessing/: Excel-zu-Parquet-Datenaufbereitung
  • src/optimization/: Pyomo-Modell, Solver-Lauf, Ergebnisexport
  • webapp/backend/: FastAPI-App und Job-Orchestrierung
  • webapp/frontend/: React/Vite-Frontend
  • data/input/: lokale Eingabedateien
  • data/processed/: lokale Preprocessing-Ausgaben
  • data/out/: lokale Ergebnisartefakte
  • var/jobs/: persistente Webapp-Jobdaten
  • docs/: Architektur- und Kommunikationsdokumentation
  • notebooks/: Analyse- und Modellnotizen
  • results/: Solver-Debugartefakte wie iis.ilp

Lokale Kommandos

Backend starten:

uv run python -m uvicorn webapp.backend.main:app --reload

Frontend starten:

cd webapp/frontend
npm install
npm run dev

Preprocessing direkt ausfuehren:

uv run python src/preprocessing/exploration_preprocess.py

Optimierung direkt ausfuehren:

uv run python src/optimization/run_optimization.py --data-dir data/processed --solver highs

Docker-All-in-One:

docker compose up --build

Laufzeit und Solver

Unterstuetzte Solver sind aktuell highs, gurobi und scip, sofern lokal installiert und fuer Pyomo verfuegbar. Im Docker-Image wird gurobipy installiert. Fuer Gurobi wird entweder eine Lizenzdatei ueber GRB_LICENSE_FILE oder WLS-Umgebungsvariablen verwendet:

  • GRB_LICENSE_FILE
  • GRB_WLSACCESSID
  • GRB_WLSSECRET
  • GRB_LICENSEID

Die Webapp prueft Solver-Verfuegbarkeit ueber /api/health.

Entwicklungsregeln fuer Agenten

  • Aendere keine Eingabe-, Ergebnis- oder Jobdaten ohne expliziten Grund.
  • Behandle var/jobs, data/out, data/processed und results als erzeugte Artefakte, sofern die Aufgabe nicht genau diese Dateien betrifft.
  • Respektiere bestehende fachliche Logik im Optimierungsmodell. Viele Grenzen sind hart kodiert und fachlich motiviert.
  • Bei Aenderungen an model_builder.py immer pruefen, ob Export, Visualisierung und Warmstart noch konsistent sind.
  • Bei Aenderungen am Excel-Output die Backend-Parser in webapp/backend/main.py mitdenken. Sie lesen konkrete Sheet- und Spaltenstrukturen.
  • Bei Aenderungen an API-Antworten das Frontend in webapp/frontend/src/App.jsx synchron halten.
  • Die Preprocessing-Datei ist notebookartig und teilweise redundant. Kleine, lokale Korrekturen sind besser als grosse Refactors ohne Tests.
  • Keine Gurobi-Lizenzdateien, Credentials oder lokale Pfade committen.
  • UI und Backend muessen auch ohne Gurobi sinnvoll starten koennen, wenn HiGHS verfuegbar ist.

Validierung

Es gibt derzeit keine klar etablierte automatisierte Testsuite. Je nach Aenderung sind diese Checks sinnvoll:

uv run python src/preprocessing/exploration_preprocess.py
uv run python src/optimization/run_optimization.py --data-dir data/processed --solver highs --time-limit 60
cd webapp/frontend && npm run build

Bei Backend- oder Webapp-Aenderungen zusaetzlich:

uv run python -m uvicorn webapp.backend.main:app --reload

Dann im Browser oder per API pruefen:

  • /api/health
  • Upload ueber Frontend
  • Statuspolling
  • Logs
  • Download von output.xlsx
  • Download von warmstart.json
  • Plots fuer Monatsfluesse und Kapazitaetszeitreihen

Bekannte Besonderheiten

  • Die Bergbauwoche beginnt fachlich am Samstag. Im Modell wird dafuer ein Datum-plus-zwei-Tage-Shift zur ISO-Woche verwendet.
  • Lieferabweichungen und Mischungsverhaeltnisse beziehen sich auf Lieferungen, nicht auf Bunkerabfluss.
  • no_three_in_a_row ist laut README aktuell auf <= 3 gelockert.
  • Bei Infeasibility kann Gurobi ein IIS nach results/iis.ilp schreiben.
  • Der Projektname in Metadaten und README ist teilweise noch POC1; fachlich entspricht das dem aktuellen LEAG-COALLOG-Prototyp.