GLM Shock Explorer

Interaktive Schock-Simulation für alle Länder und Produkte auf einem 3D-Globus. Klicke ein Land → sieh dessen Top-Export-/Import-Produkte → wähle eine Beeinträchtigung → das Modell berechnet in Echtzeit die direkten und indirekten Folgen über die globalen Vorleistungsketten (OECD ICIO 2022, 80 Länder × 50 Sektoren).

Zielgruppe: Forscher im PROVIDER-Projekt.

Start

./start.sh

Legt beim ersten Lauf ein .venv an, installiert Abhängigkeiten, berechnet die Leontief-Inverse L und Ghosh-Inverse G (~5 s, danach gecacht unter backend/.cache/) und öffnet http://localhost:8099.

Bedienung

Startseite: Beim Öffnen erscheint eine Startseite mit einer Szenario-Auswahl (Kacheln), „🌍 Freie Erkundung" und „▶ Demo-Modus". Ein Klick auf eine Kachel lädt das Szenario direkt; ein Klick auf das Logo (oben links) führt jederzeit zur Startseite zurück. Geteilte Permalinks überspringen die Startseite und gehen direkt ins Ergebnis.

1. Land anklicken → Panel zeigt Top-Export-/Import-Produkte.
2. Produkt wählen → Schock-Box erscheint.
3. Schocktyp wählen:
   • Angebotsausfall (Ghosh-Forward): Das Land kann das Produkt nicht mehr produzieren; wer bezieht von dort und leidet?
   • Vorleistungs-Engpass (Leontief-Backward): Inputs aus diesem Land fallen aus; welche Abnehmer-Industrien stocken?
4. Schwere-Slider schieben → Folgen werden live neu berechnet.
5. Ergebnis: KPI-Header (Gesamteffekt, betroffene Sektoren, DEU-Effekt, größter Treffer), Globus (Wellen am Ursprung, Bubbles nach Effektstärke, Arcs zu Top-Betroffenen), Ranking-Listen (Länder, Sektoren, Deutschland).

Chokepoints: Gelbe ▲-Marker sind Handelsrouten/Häfen (Hormuz, Taiwanstraße, Santos, Malakka, Suez, Bab al-Mandab, Bosporus). Klick → die Route wird gesperrt; das Modell schockt die Produzenten-Knoten, deren Durchsatz darüber läuft (z. B. Hormuz → Golf-Öl B06), und propagiert vorwärts (Ghosh). Definition in backend/data/chokepoints.json (leicht erweiterbar).

Länder ohne Produktdaten (z. B. Taiwan, im BACI-Export nach ROW aggregiert) bieten einen Sektor-Fallback statt der Produktliste.

Architektur

frontend/index.html   globe.gl Single-File-App (CDN, kein Build)
backend/app.py        FastAPI: /api/meta, /api/country/{iso}, /api/shock + statisches Frontend
backend/engine.py     vektorisierte Leontief/Ghosh-Mathematik (reine Funktionen, getestet)
backend/data_loader.py lädt A/x/Labels, rechnet+cacht L/G, baut Land→Produkt-Index
backend/results.py    baut aus dx-Vektor die JSON-Antwort (KPIs, Rankings, Arcs)
backend/constants.py  Sektornamen, EU-Liste
backend/tests/        pytest für die Engine

Datenquellen (read-only, aus dem GLM-Projekt bzw. supply-radar-Export):

• 01_Daten/globale-lieferketten-matrix/data/processed/A_matrix.npy, x_vector.npy, sector_labels.txt
• 04_Apps/supply-radar/public/data/product_summaries.json, product_index.json, country_meta.json

Tests

cd backend && python3 -m pytest tests/ -q

Methodik-Hinweise

• Die A-Matrix ist sektoraufgelöst (4050×4050). Das gewählte Produkt liefert die Story und den Sektor; geschockt wird die Land×Sektor-Kapazität. Ein Produktschock trifft also den ganzen ICIO-Sektor — bewusste MVP-Vereinfachung.
• Bei Angebotsschocks ist Ghosh das primäre Modell, bei Vorleistungsengpässen Leontief.
• Basisjahr 2022 (einzige vorhandene Matrix).

Tutorial & Hintergrund

In der App erklärt ein integriertes Tutorial (Button „?" oben oder „📖 Tutorial & Hintergrund" auf der Startseite) in vier Tabs Daten & Quellen (ICIO 2025, BACI HS07, 4.050 Knoten, Faktentabellen), Methodik (technische Koeffizienten, Leontief/Ghosh-Formeln, SPA, Chokepoint-Modell), Bedienung (Schritt-für-Schritt) und Grenzen & Kontext (Modellgrenzen, PROVIDER-AP4/AP7). Inhalt steht in frontend/index.html unter const TUT_TABS.

LLM-Funktionen (AP4 + AP7)

Zwei Claude-gestützte Funktionen, aktiv sobald ANTHROPIC_API_KEY gesetzt ist:

• News → Schock (AP4): Auf der Startseite eine Schlagzeile/Meldung eingeben (oder ein Beispiel anklicken) → das LLM (claude-opus-4-8, strukturierte Extraktion) erkennt Ort + Sektor + Schweregrad + Schocktyp. Statt sofort zu feuern erscheint eine editierbare Erkennungs-Karte (Human-in-the-Loop):
  • Konfidenz der Zuordnung (Badge, farbcodiert hoch/mittel/niedrig),
  • Begründungs-Highlighting — die auslösenden Textstellen sind in der Schlagzeile farbig markiert (Ort/Produkt/Ereignis/Route), mit Legende,
  • korrigierbare Felder (Schocktyp-Toggle, Land/Sektor- bzw. Chokepoint-Dropdown, Schwere-Slider) — erst „▶ Simulieren" löst die Simulation aus. Das ist der interaktive PROVIDER-Durchstich „Nachricht → (geprüfte) Parametrisierung → Simulation".
• Ergebnis erklären (AP7): Im Ergebnis-Panel der Button „🧠 Ergebnis erklären" → eine prägnante deutsche Analyse des Schocks (Modell, Hauptbetroffene, Kette, Deutschland-Bezug), gestützt auf die berechneten Zahlen.

Ohne Key bleiben beide Funktionen ausgeblendet; der Rest der App läuft normal weiter. Setzen: export ANTHROPIC_API_KEY=sk-ant-... vor ./start.sh (oder in .env, wird von start.sh geladen).

Bewertung der Schockgröße: Jeder Schock erhält eine einfache, regelbasierte Einordnung — eine globale Stufe (gering/moderat/erheblich/kritisch, Anteil am Weltoutput) und eine Deutschland-Relevanz (Anteil am DEU-Output). Sie erscheint als farbiges „Größe: …"-Label im Gesamteffekt-KPI und — nach einer News-Analyse — prominent im Banner („Schockgröße: … · Deutschland: …"). Schwellen in backend/results.py (GLOBAL_BANDS, DEU_BANDS).

Szenario-Unsicherheit & Wahrscheinlichkeit

Im Ergebnis-Panel öffnet 📊 Unsicherheit & Wahrscheinlichkeit die bedingte Wirkungsverteilung des aktuellen Schocks: Schwere (und bei Chokepoints der Knotenausfall) werden per Monte-Carlo variiert → Histogramm des DEU-Schadens, Erwartungswert ± 90 %-Intervall, Punktschätzung und ein Schwellen-Slider für P(DEU-Schaden > x). Pro Knoten ist der Schaden linear in der Intensität, daher reicht ein Koeffizient × Zufallsmatrix (ms-schnell). Wichtig: Das ist die bedingte Verteilung gegeben das Ereignis — die Eintrittswahrscheinlichkeit des Ereignisses selbst ist exogen und nicht enthalten. Backend: run_scenario_mc in montecarlo.py, Endpoint /api/scenario-mc.

Systemrisiko (Monte-Carlo)

Der Startseiten-Button 🎲 Systemrisiko öffnet eine Monte-Carlo-Analyse aus Deutschland-Perspektive: Statt ein Szenario zu raten, werden ~2.000 zufällige Angebotsschocks gezogen (1–3 Ursprungsknoten, gewichtet nach Bruttoproduktion, zufällige Schwere) und über die Ghosh-Inverse propagiert — vektorisiert auf den DEU-Spalten (~0,2 s). Ausgaben:

• Schadensverteilung für Deutschland (Histogramm, Mittel/p95/Maximum),
• verwundbarste deutsche Sektoren (mittlerer Verlust + Trefferhäufigkeit über alle Ziehungen),
• größte Auslands-Risiken für DEU (analytische Kritikalität x·ΣG, klickbar → als Einzelschock simulieren). „🎲 Neu würfeln" zieht ein neues Ensemble (neuer Seed). Backend: backend/montecarlo.py, Endpoint /api/montecarlo. Lesart: strukturelle Vulnerabilitäts-Indikatoren, keine Prognose.

Transmissionspfade (Sankey)

Im Ergebnis-Panel öffnet ▸ Pfade ein Sankey-Diagramm: Es zeigt, wie sich der Schock vom Ursprung entlang der Lieferketten vorwärts ausbreitet (Structural Path Analysis über die Ghosh-Matrix B: dx = Δv·(I+B+B²+…), jeder Pfad ein Term). Beam-Search liefert die ~24 dominanten Ketten mit ihrem Beitrag zum Folgeschaden, darunter als gerankte Liste (z. B. „BRA Landwirtschaft → BRA Nahrungsmittel → CHN Gastgewerbe"). Endpoint /api/transmission.

Demo-Modus

Der ▶ Demo-Button (oben links) spielt automatisch eine Playlist aus 7 Szenarien ab (Hormuz, Taiwanstraße, Brasilien-Soja, Santos, China-Elektronik, Deutschland-Kfz, Suez) — jeweils ~7 s mit Titel-Banner, dann das nächste, in Endlosschleife. Jede echte Interaktion (Globus/Panel anklicken, Esc, „⏹ Stop") bricht sofort ab. Ideal für Messen/Vorträge. Die Playlist steht in frontend/index.html (const DEMO = [...]) und ist leicht erweiterbar.

Teilen / Permalinks

Jeder Schock wird als URL-Hash kodiert (z. B. #m=cp&cp=hormuz&sev=80 oder #m=co&t=ghosh&c=BRA&hs6=120100&sev=70). Der „🔗 Link"-Button im Ergebnis-Panel kopiert die aktuelle URL; beim Öffnen wird der Schock automatisch reproduziert. Ideal zum Teilen und Zitieren konkreter Szenarien.

Status

Feature-komplett (Phase 1 + 2 + LLM): Angebotsausfall (Ghosh), Vorleistungs-Engpass (Leontief-Import), Chokepoints/Handelsrouten als ▲-Marker, Transmissionspfade-Sankey, News→Schock + LLM-Erklärung (Claude), teilbare Permalinks, Auto-Demo-Playlist, KPI-Header, Ranking-Panels, Globus-Bubbles/Arcs/Wellen.

Mögliche Erweiterungen: weitere Chokepoints/Jahre, Export der Sankey/Reports, Mehrfach-Schocks.

Design-Spec: 01_Daten/globale-lieferketten-matrix/docs/superpowers/specs/2026-06-17-glm-shock-explorer-design.md

Daten (nicht im Repository enthalten)

Dieses Repository enthält nur den Anwendungscode, nicht die Eingangsdaten. Die Schock-Berechnung benötigt zur Laufzeit folgende Datensätze, die jeweils unter den Bedingungen ihrer Urheber zu beziehen sind (Attribution erforderlich):

• OECD ICIO (Inter-Country Input-Output Tables) — A-Matrix und Output-Vektor. Quelle: OECD, https://www.oecd.org/sti/ind/inter-country-input-output-tables.htm.
• CEPII BACI (HS07) — Handelsflüsse für die Produkt→Land-Zuordnung. Quelle: CEPII, https://www.cepii.fr/CEPII/en/bdd_modele/bdd_modele.asp.
• Aggregierte Land-/Produkt-Metadaten aus dem internen supply-radar-Export.

Die App erwartet diese Dateien an den in backend/data_loader.py definierten Pfaden.

Zu den mitgelieferten Artefakten im Repo:

• branche_map.json und die Beispiel-Rechnungen (frontend/sample_org_invoices.csv) sind eigene, synthetische Artefakte unter der MIT-Lizenz dieses Repositorys. Die Beispiel-Rechnungen enthalten keine realen Betriebsdaten.
• backend/data/chokepoints.json ist gemischt: Die Korridor-Topologie (id, name, Koordinaten, Knotenzuordnung) ist kuratiert und MIT-lizenziert. Die weight-Felder sind dagegen aggregierte Kennzahlen, abgeleitet aus OECD ICIO (tools/chokepoint_weights.py rechnet sie als Export-Intensität aus A und x) — rund 20 Fließkommazahlen, die keine Rekonstruktion der Ausgangsdaten erlauben, aber eben keine Eigenschöpfung sind.

Bereitstellung fürs Konsortium (Standalone Docker)

Für die Verteilung an das PROVIDER-Konsortium läuft die App als self-contained Docker-Image mit einem reduzierten Soja-Datenpaket — keine 125-MB-Vollmatrix, keine Monorepo-Nachbarordner, kein API-Key nötig.

Schritt 1 — Datenpaket erzeugen (einmalig, lokal mit vorhandener Vollmatrix):

cd tools && python3 build_subset.py
# -> data/subset/ : 19 Länder, 950 Knoten, ~72 % Welt-Output, vorberechnete L/G (~24 MB)

Das Subset deckt die Soja-Lieferkette + die Länder der eingebauten Demo-Story ab. Andere Auswahl: python3 build_subset.py --countries BRA,USA,DEU,CHN,ROW.

Schritt 2 — Image bauen und ausliefern:

docker build -t glm-shock-explorer:soy .
docker run -p 8099:8099 glm-shock-explorer:soy            # -> http://localhost:8099

Optional mit LLM-Features (jeder eigenen Key):

docker run -p 8099:8099 -e ANTHROPIC_API_KEY=sk-ant-... glm-shock-explorer:soy

Das Backend wählt das Datenpaket über die Env-Variable GLM_DATA_DIR (im Image auf /app/data/subset gesetzt); ohne sie läuft dieselbe App im Vollmodus gegen die Monorepo-Daten.

⚠️ Das gebaute Image darf nicht öffentlich verteilt werden. Es enthält unter /app/data/subset aus OECD ICIO abgeleitete Matrizen (inkl. vorberechneter $L$/$G$). Die OECD-Nutzungsbedingungen decken deren Weiterverbreitung nicht ab — eine öffentliche Container-Registry, ein GitHub-Release-Asset oder ein offener Download wären genau das. Zulässig ist die zugangsbeschränkte Weitergabe im Konsortium (private Registry, docker save-Tarball auf gesichertem Weg). Wer das Image ohne diese Bindung braucht, baut es sich mit build_subset.py aus einer selbst bezogenen ICIO-Lizenz.

Deshalb liegt data/subset/ auch nicht im Git (siehe .gitignore) — dieses Repository enthält ausschließlich Code.

Mathematischer Hinweis: Das Subset ist eine reduzierte, in sich konsistente Teilwelt. $L$/$G$ werden aus der zugeschnittenen Matrix neu berechnet — Wirkungspfade über weggelassene Länder entfallen, die Zahlen weichen daher von der Vollmatrix ab (Details in data/subset/manifest.json). Für Demo und Methoden- Vermittlung ausgelegt, nicht als verlustfreier Ausschnitt.

Lizenz

Der Code dieses Repositorys steht unter MIT © 2026 PROVIDER Consortium.

Ausgenommen von der MIT-Lizenz:

• frontend/assets/provider-logo.jpg — Logo des Verbundprojekts PROVIDER. Kennzeichen des Konsortiums, keine Nutzungsfreigabe über die MIT-Lizenz; Verwendung nur mit Zustimmung des Konsortiums. Beim Forken/Ableiten bitte entfernen oder ersetzen.
• frontend/assets/countries-110m.geojson — Natural Earth (Admin-0 Countries, 1:110m), Public Domain. Attribution nicht erforderlich, aber erbeten: https://www.naturalearthdata.com.

Herkunft und Lizenzen aller Drittbestandteile: THIRD-PARTY-LICENSES.md.

Entwickelt im Rahmen des BMFTR-geförderten Verbundprojekts PROVIDER.