# pyTREMOD Architektur

Das Ziel dieser System- und Architekturdokumentation ist es, eine verständliche, nachvollziehbare und systematische Grundlage für die Kommunikation und Dokumentation der Architektur des neu entwickelten Systems zu schaffen, indem relevante Ziele und Anforderungen festgehalten, Abrenzungen und Definitionen zusammengetragen sowie der inhaltliche und technische Aufbau beschrieben werden.

## Einführung und Ziele

Einführung

Das Emissionsberechnungsmodell „TREMOD“ (Transport Emission Model) wurde vom ifeu-Institut im Auftrag des Umweltbundesamtes entwickelt und kontinuierlich fortgeschrieben. Das Modell bildet den motorisierten Verkehr in Deutschland hinsichtlich seiner Verkehrs- und Fahrleistungen, Energieverbräuche und der zugehörigen Luftschadstoffemissionen typischerweise für den Zeitraum 1960 bis 2050 ab. Die mit TREMOD berechneten Emissionen von Treibhausgasen und Luftschadstoffen sind unter anderem die Grundlage der deutschen Emissionsberichterstattung für den Sektor „Verkehr“. Das Emissionsberechnungsmodell TREMOD (Transport Emission Model) wurde vom ifeu-Institut im Auftrag des Umweltbundesamtes entwickelt und wird kontinuierlich fortgeschrieben, wobei das Modell ursprünglich in MS Access implementiert wurde.

Ziele

Angesichts stetig steigender Anforderungen an die Datenverarbeitung und der Notwendigkeit zur Integration komplexerer Berechnungen (wie z.B. die bereits efolgte detaillierte Erfassung von Nicht-CO2-Effekten des Flugverkehrs), ist eine Überarbeitung der technischen Basis zwingend erforderlich. Das übergeordnete Ziel dieses Vorhabens ist damit eine Migration in die Programmiersprache Python, um technische Engpässe aufgrund unter anderem der steigenden Datenmenge und der geringen Ausführungsgeschwindigkeit von MS-Access zu beseitigen und die Rechenzeiten erheblich zu verkürzen. Zugleich sollen technische, inhaltliche und methodische Altlasten, die sich in der Access-Version (teilweise auch aus archiviarischen Gründen) seit den 1980er bzw. 1990er Jahren aufbauten und erhielten, entfernt und ein kontinuierlicher Wissenstransfer (fachlich und technisch) durch explizite Dokumentation gewährleistet werden.

### Aufgabenstellung

Die technische Überführung in die Programmiersprache Python zielt darauf ab, die bisherige Datenbank- und Softwarearchitektur zu überarbeiten. Konkret sind folgende technische Ziele definiert:

1. Plattformunabhängigkeit und Ausführung: Die neue TREMOD-Version muss systemunabhängig sein und vor allem auf Windows-Festrechnern selbstständig lauffähig sein.

2. Architekturverbesserung: Die Softwarearchitektur soll das mehrschichtige Architekturmuster verwenden und die Datenbank-Schicht von der Berechnungs- und der Präsentations-Schicht (Benutzeroberfläche/-interaktion) klarer abgrenzen.

3. Applikationsaufbau: Aufteilung des Access-Modells in eine Entwicklungs- und eine **Nutzungsvariante. Das Hauptunterscheidungsmerkmal ist der Umfang der Daten- und Berechnungsschritte. Die Entwicklervariante beinhaltet die Datenaufbereitung und sämtliche Modellberechnungen, während die Nutzungsvariante nur jene (Zwischen-)Ergebnis-, Definitions- und Berechnungstabellen, die notwendig sind, um die bisherig verfügbaren Features über die Formulare der Access-Version darzustellen.

4. Datenbanktechnologie: Als Datenbanktechnologien sollen primär PostgreSQL (für die Entwicklungs-Variante und als zentrale Datenbasis) und ausschließlich SQLite (für die Nutzungs-Variante) eingesetzt werden.

5. Funktionalität und Benutzeroberfläche: Alle Funktionen der bisherigen Benutzeroberfläche von TREMOD (z. B. MS-ACCESS Formulare) sollen in der neuen Version beibehalten werden.

### Qualitätsziele

Die Migration ermöglicht die Beseitigung von Altlasten und die Erreichung höherer Präzision und Wartbarkeit:

1. Ergebniskonsistenz: die grundlegende Methodik von TREMOD, einschließlich der Formeln und Algorithmen ist, soweit möglich beizubehalten, um eine weitestgehende Ergebnisgleichheit zwischen der ursprünglichen MS-Access-Version und der neu entwickelten Python-Version zu gewährleisten. Dies stellt sicher, dass die Emissionsberechnung analog zu den Vorjahren erfolgen kann und es durch die technische Umstellung zu keinen statistischen Brüchen in den Emissionszeitreihen kommt.

2. Softwarearchitektur: pyTREMOD basiert auf dem mehrschichtigen Architekturmuster (layered architecture pattern), wobei eine bessere Wartbarkeit durch die Trennung von Präsentationsschicht, also dem User Interface, Anwendungslogik und Datenzugriff zu erreichen. Die Architektur umfasst dabei typische Schichten wie die Präsentationsschicht, Geschäftslogikschicht (Emissionsberechnungen) und Datenzugriffsschicht.

3. Integration neuer Methoden: Die neue Architektur muss die Integration komplexer, detaillierter Methoden unterstützen. Die Implementierung der kommenden Emissionsfaktoren des Straßenverkehrs aus HBEFA Version 5.1 (geplant für Herbst 2025) ist über eine separate API-Schnittstelle in das migrierte TREMOD-Modell zu integrieren und einer Qualitätsprüfung zu unterziehen.

4. Datenstruktur: Obsolete Daten und aufgrund der Restriktionen von MS-Access notwendigen Zwischentabellen werden entfernt, um mehr Übersichtlichkeit zu schaffen. Die Daten- und Tabellennomenklatur wird konsoidiert. Der Datenzugriff erfolgt über die Persistenzschicht, dafür verantwortlich, Anfragen entgegenzunehmen, um Daten abzurufen oder zu speichern, indem sie beispielsweise SQL-Anweisungen ausführt, die die entsprechenden Daten aus der Datenbank abrufen und für weitere Operationen (zentral) bereitstellt.

5. Wissenstransfer und Dokumentation: Zur Gewährleistung des Wissenstransfers wird die IT-seitige Umsetzung für das neue Modell in kompakter Form dokumentiert. Zudem wird eine knappe Installations- und Bedienungsanleitung erstellt. Das Refactoring selbst trägt dazu bei, den Code bzw das Modell einfacher, sauberer und leichter verständlich zu machen.

### Stakeholder

Die wichtigsten Stakeholder des TREMOD-Migrationsprojekts sowie ihre Erwartungen sind in nachstehender Tabelle gelsitet.

Stakeholder im TREMOD-Migrationsprojekt
Rolle | Kontakt | Erwartungshaltung
--- | --- | ---
Auftraggeber | Umweltbundesamt, Wörlitzer Platz 1, 06844 Dessau-Roßlau (UBA) | TREMOD (MS-Access Applikation) soll in eine technisch überarbeitete Version in der Programmiersprache Python überführt werden, die systemunabhängig und auf Windows-Festrechnern selbstständig lauffähig ist, und dabei die Funktionen der bisherigen Benutzeroberfläche beibehält, Ergebnisgleichheit mit der alten Access-Version gewährleistet und die Emissionsdaten für die deutsche Emissionsberichterstattung (NIR, VEdV, KSG) bereitstellt.
Entwickler | ifeu - Institut für Energie- und Umweltforschung Heidelberg gGmbH, Wilckensstr. 3, 69120 Heidelberg (ifeu) | Die Überführung des TREMOD-Modells in eine systemunabhängige Python-Version unter Beibehaltung aller bisherigen Benutzeroberflächen-Funktionen. Einfachere Wartbarkeit und Erweiterbarkeit durch die Überführung auf Python und die Nutzung eines mehrschichtigen Architekturmusters sowie Konsolidierung der fachlichen und technischen Dokumentation.

## Randbedingungen

Aus der Aufgabenstellung ergeben sich folgende wesentliche architektonische Randbedingungen, die eingehalten werden müssen.

Architektonische Randbedingungen
Kategorie | Randbedingung
--- | ---
Technologie/Sprache | Die gesamte Anwendung (Berechnung und Benutzeroberfläche) ist in Python und mit für diese Sprache frei verfügbaren (Open-Source) Frameworks und Modulen zu entwickeln, wie beispielsweise PySide, Pandas, Numpy.
Datenbank (Dualität) | Es ist die Verwendung von PostgreSQL (Entwicklung/Remote) und SQLite (Nutzungs-Variante/Offline-Entwicklung) zu Verwenden.
Legacy-Datenabgleich | Ergebnisse und Zwischenergebnisse der neuen Version müssen mit der letzten MS-Access-Version verglichen und Abweichungen dokumentiert und begründet werden.
Schnittstellen | Die Anwendung muss weiterhin die Übergabe der TREMOD-Ergebnisse im ZSE-Format (Zentrales System Emissionen) ermöglichen. Ferner werden die Emissionsfaktoren des HBEFA über dessen API in das System eingebunden und definierte qualitätssichernden Routinen nach Abfrage der Daten ausgeführt.
Quellcode-Verwaltung | Die Versionsverwaltung muss über Git (intern gehostete GitLab-Instanz) erfolgen, und der Quell-Code muss dem UBA zur Verfügung gestellt werden.
Deployment / Hardware | Die Nutzervariante muss auf üblichen Büro-Festrechnern oder -Notebooks mit der aktuell verwendeten Windows OS Version des Umweltbundesamtes lauffähig und nutzbar sein. Als Referenz dient ein Notebook mit Windows 11 und 8GB RAM. Für die Entwicklungsvariante müssen alle notwendigen Abhängigkeiten zur Inbetriebnahme/Lauffähigkeit auf Drittsystemen dokumentiert sein. Die Hardwarelimitationen der Nutzer-Variante gelten hier nicht.
Freigabe | Die fachliche und methodische Freigabe bei Änderungen gegenüber der Access-Version, beispielsweise durch die Implementierung der neuen HBEFA-Version obliegt dem Umweltbundesamt.
Versionierung | Die Versionierung erfolgt gemäß der Fertigstellung fachlicher Inhalte, z.B. Emissionsinventar nach Absprache mit dem UBA.
Funktionaler Umfang (Scope) | Das Modell deckt alle relevanten Verkehrsträger für die Emissionsbilanzierung ab, wie Straßenverkehr (Pkw, LNF, SNF, Busse, MZR), Schienenverkehr, Binnenschifffahrt, Mobile Maschinen und Luftverkehr (von Deutschland abgehender Flugverkehr bis zur ersten Zwischenlandung). Die Nutzervarianten bietet für all diese Kategorien ein entsprechendes User-Interface, dass die Möglichkeiten der Access-Version wiederspiegelt. Ferner werden die Exportschnittstellen für alle entsprechenden Fachdaten (z.B. ZSE-Schnittstelle) bereitsgestellt. Alle Funktionen der bisherigen MS-ACCESS Benutzeroberfläche (z. B. Formulare wie „Common data“, „Results“) sollen in der neuen Version beibehalten werden.

## Kontextabgrenzung

Das System im Zentrum dieser Abgrenzung ist das migrierte TREMOD-Modell (Transport Emission Model) in seiner neuen Python-basierten Architektur. Der Zweck des Systems ist die Modellierung des motorisierten Verkehrs in Deutschland zur Ermittlung von Verkehrs- und Fahrleistungen, Energieverbräuchen und den zugehörigen Emissionen von Treibhausgasen und Luftschadstoffen, unter anderem für für die deutsche Emissionsberichterstattung (NIR, Vorläufige Emissionsdaten des Vorjahres - VEdV nach KSG).

### Fachlicher Kontext

Der fachliche Kontext beschreibt die Kommunikationspartner (Interessenten und Nachbarsysteme) und die ausgetauschten Datenströme, die für die Emissionsberechnung relevant sind.

Anmerkung: Hinsichtlich der weiteren Nutzergruppen könnte sich der Kreis der Nutzenden aufgrund der Nutzungsbedingungen aktuell verengen oder aufgrund regulatorischer Vorgaben erweitern.

Fachlicher Kontext des migrierten TREMOD-Modells

Nachstehende Tabelle präzisiert den skizzierten Fachkontext sowie die Daten- und Informationsflüsse.

Fachlicher Kontext und Datenflüsse des TREMOD-Modells
Kommunikationspartner | Bereitstellung/Eingabe (Input) | Ausgabe (Output)
--- | --- | ---
Umweltbundesamt (UBA) / Hauptnutzer | CO2-Emissionsfaktoren Kraftstoffe und Strom; Fachliche Freigabe der Methodik | Ergebnisse im ZSE-Format (Zentrales System Emissionen); VEdV (Vorläufige Emissionsdaten des Vorjahres); Emissionsberichterstattung des nationalen Inventarberichts (NIR) und Informative Inventory Report (IIR).
Kraftfahrtbundesamt (KBA) | Bestands- und Neuzulassungsdaten aus dem zentralen Fahrzeugregister | Keine direkten Ausgaben.
Statistisches Bundesamt (DESTATIS) | Sonderabfragen zur Binnenschifffahrt, zum Flugverkehr, oder Busverkehr | Keine direkten Ausgaben.
Deutsche Bahn AG | Verkehrsleistungen, Betriebsleistungen, Auslastungsgrade nach Traktionsarten (z.B. Dieselanteil), detaillierte Betriebsdaten (Zuggattungen, Baureihen, Motoren), den erfassten Dieselverbrauch der DB AG, die Aufteilung des Dieselkraftstoffverbrauchs auf Verkehrsarten wie Personenfernverkehr, Personennahverkehr und Güterverkehr inklusive Rangieren, sowie baureihenspezifische Emissionsfaktoren. | Keine direkten Ausgaben.
AG Energiebilanzen / BAFA | Absatzzahlen von Kraftstoffen (z. B. Diesel, Otto, Biokraftstoffe); Amtliche Mineralöldaten (AMS) zur VEdV-Ermittlung. | Keine direkten Ausgaben.
HBEFA-Schnittstelle | Emissionsfaktoren und spezifische Verbrauchsfaktoren des Straßenverkehrs | Keine direkten Ausgaben.
Weitere Modelle / Prognosen (BMV, DLR) | Verkehr in Zahlen (ViZ) zum Abgleich der Verkehrs- und Fahrleistungen, Prognosen zur Verkehrsleistungsentwicklung und sozioökonomische Randbedingungen (z. B. Gleitende Langfrist-Verkehrsprognose 2022) | Keine direkten Ausgaben.
Weitere Nutzer (Institutionen und Unternehemen, wie ifeu, DB AG, BASt, Destatis) | ggf. Szenarienanpassungen; kein Input. | Emissionsfaktoren, Emissionen, Fahrzeugbestände, Aktivitätsdaten, etc.

### Technischer Kontext

Technischer Kontext und Datenflüsse des TREMOD-Modells
Komponente | Beschreibung
--- | ---
Inputdaten | Diese werden in Formaten, wie PDF-Berichte, CSV- oder Excel-Dateien bereitgestellt und durch Experten mit Hilfe von Tabellenkalkulationsprogrammen oder Analyseprogrammen geprüft und konsolidiert. Die Emissionsfaktoren des Straßenverkehrs werden über die API des HBEFA übermittelt. Diese Daten werden über ETL-Prozesse in die zentrale Postgresdatenbank der Enwickler-Variante geladen.
Entwicklungs-Variante | Die Entwicklungsvariante beinhaltet Teile der Datenaufbereitung und sämtliche komplexen Modellberechnungen (wie zum Beispiel die Integration des HBEFA 5.1 über eine API).
Nutzungs-Variante | Die Nutzungsvariante (auch Nutzer-Variante genannt) wird nur jene (Zwischen-)Ergebnis-, Definitions- und Berechnungstabellen enthalten, die notwendig sind, um die bisherig verfügbaren Features über die Formulare der Access-Version darzustellen. Sie soll auf einem Büro-Festrechner oder -Notebook unter MS-Windows lauffähig sein.
Web-API | Eine WEB-API zum Abruf von Ergebnistabellen ist optional und soll aktuell nicht umgesetzt werden.
Versionsverwaltung | Die Versionsverwaltung erfolgt mittels Git über eine ifeu-intern gehostete GitLab-Instanz. Der Quellcode entwickelter Versionen soll auch auf ein Cloud-Repository, das durch den Auftraggeber festgelegt wird, gespiegelt werden.

Externe technische Schnittstellen

- HBEFA 5.1 API: REST-Schnittstelle zum Bezug von Emissionsfaktoren.

- SQL-Schnittstelle: JDBC/ODBC-Verbindung zu PostgreSQL bzw. lokale Datei-Schnittstelle für SQLite.

- ZSE-Export: CSV/Excel-basierte Dateischnittstelle für das Umweltbundesamt.

## Lösungsstrategie

Um die gesetzten Ziele zu erreichen, basiert die Lösung auf folgenden strategischen Entscheidungen:

1. Migration zu Python: Ablösung der MS-Access-Basis durch eine moderne, plattformunabhängige Architektur in Python. Dies ermöglicht die Nutzung leistungsfähiger Bibliotheken wie Pandas und NumPy für die Datenverarbeitung.

2. Mehrschichtarchitektur: Striktes Layering zur Trennung von UI (PySide6), Geschäftslogik und Datenzugriff (Persistence Layer), um die Wartbarkeit und Testbarkeit zu erhöhen.

3. Datenbank-Dualität: Unterstützung von PostgreSQL für die zentrale Datenhaltung in der Entwicklung und SQLite für die lokale, portable Nutzung in der Anwendervariante.

4. Automatisierte Datenaufbereitung: Integration von ETL-Prozessen zur Konsolidierung heterogener Datenquellen (Destatis, KBA, HBEFA-API).

5. Beibehaltung der Methodik: Sicherstellung der Ergebniskonsistenz durch Portierung der bewährten Berechnungsalgorithmen aus der Access-Version.

## Bausteinsicht

### Whitebox Gesamtsystem

<Übersichtsdiagramm>

Whitebox Gesamtsystem

Begründung

  Das Gesamtsystem folgt einem klassischen Schichtenmodell, das eine klare Trennung der Verantwortlichkeiten gewährleistet. Die Präsentationsschicht interagiert ausschließlich mit der Persistenzschicht, um Daten anzuzeigen oder Nutzereingaben zu verarbeiten. Die Berechnungsschicht (Business Logic) führt die komplexen Emissionsmodelle aus und nutzt ebenfalls die Persistenzschicht für den Datenzugriff, was eine Datenbankunabhängigkeit (PostgreSQL vs. SQLite) ermöglicht.

Enthaltene Bausteine

  Die Bausteine des Gesamtsystems sind nach funktionalen Schichten gegliedert:

  - Präsentationsschicht (UI): Beinhaltet die PySide6-basierten Formulare und Ansichten (z.B. MainWindow, TremodRail), die dem Nutzer den Zugriff auf Parameter und Ergebnisse ermöglichen.

  - Berechnungsschicht (Logik): Das Herzstück des Systems, welches die verkehrsträgerspezifischen Algorithmen (z.B. RailEmissions) implementiert.

  - Persistenzschicht: Abstrahiert den Zugriff auf die unterschiedlichen Datenbanksysteme (DatabaseManager) und stellt ein einheitliches API bereit.

  - Datenbankschicht: Sorgt für die physische Speicherung der Daten in PostgreSQL oder SQLite.

Wichtige Schnittstellen

  - Datenbankschnittstelle: SQL-basiertes Interface zwischen Persistenzschicht und den Datenbanken.

  - HBEFA API: REST-Schnittstelle zum automatisierten Abruf von Emissionsfaktoren (HBEFA 5.1).

  - ZSE-Export: Dateibasierte Schnittstelle (CSV/Excel) zur Übergabe der Ergebnisse an das Umweltbundesamt.

#### Benutzeroberfläche (UI)

Whitebox UI (Klassendiagramm)

Whitebox UI (Moduldiagramm)

Zweck/Verantwortung

  Die Benutzeroberfläche ermöglicht dem Anwender die Interaktion mit dem Modell, die Auswahl von Szenarien und die Visualisierung von (Zwischen-)Ergebnissen. Sie ist mit PySide6 implementiert und folgt dem Muster einer Desktop-Applikation.

## Glossar

Erstellt agelehnt an:

arc42, das Template zur Dokumentation von Software- und Systemarchitekturen. Template Version 8.2 DE. (basiert auf AsciiDoc Version), Januar 2023 Created, maintained and © by Dr. Peter Hruschka, Dr. Gernot Starke and contributors. Siehe https://arc42.org.