.. TREMOD documentation master file, created by
   sphinx-quickstart on Tue Mar 28 15:38:34 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Straßenverkehr (1A3b)
=====================

.. note::
   This project and docupage is under active development!

Für den Straßenverkehr in TREMOD werden die Fahrzeugbestände, Fahr- und Verkehrsleistungen, sowie der Energiebedarf und
die Emissionen aller in Deutschland betriebenen motorisierten Verkehrsmittel des Straßenverkehrs jährlich erfasst.
Die Ergebnisse liegen für den Zeitraum ab 1950 bis 2050 für Deutschland insgesamt (bzw. bis 1993 unterteilt für Ost- und
Westdeutschland) vor. TREMOD bildet das Inlandsprinzip (Verkehre auf deutschem Territorium) und das Energiebilanzprinzip
(in Deutschland für den Straßenverkehr abgesetzte Energiemengen) ab.

**Hinweis:** Die nachfolgende Dokumentation fokussiert auf die Modelllogik von TREMOD. Weitere Informationen zu
den Datenquellen, Annahmen und Ergebnissen und Berechnungsmethoden werden in den veröffentlichen TREMOD-Berichten für
das UBA dokumentiert.

**Aktuelle Version:** 7.01 (Arbeitsversion)

.. toctree::
   :maxdepth: 3
   :caption: Contents:

1. Methodik
-----------------------
Der Energieverbrauch und die Emissionen pro Jahr werden bottom berechnet und können anschließend differenziert oder in
aggregierter Form in TREMOD abgefragt werden.
Die Berechnung erfolgt in den **Modulen** stock (Bestände), mileage (Fahr- und Verkehrsleistung) und emissions
(Energieverbrauchs- und Emissionsfaktoren) statt, siehe Abbildung.

**Schema Emissionsberechnung Straßenverkehr**

.. image:: images/TREMOD_road_schema.png

TREMOD verwendet verschiedene **Definitionen** für Fahrzeugmerkmale, von der Fahrzeugkategorie (oberste Ebende)
bis hin zur Fahrzeugschicht (differenzierteste Ebene). Dazwischen existieren weitere Ebenen, z.B. Segment (
Fahrzeugkategorie + Größenklasse + Antrieb) oder Konzept (Fahrzeugkategorie + Antrieb + Emissionsstandard).
Folgende Tabelle stellt diese am Beispiel Lkw dar.

.. list-table:: **Fahrzeugdefinitionen**
   :widths: 30 20 30
   :header-rows: 1

   * - Defintion
     - Abkürzung
     - Beispiel
   * - Fahrzeugkategorie
     - Fzkat
     - Lkw
   * - Größenklasse
     - GK
     - 12–14t (zGG)
   * - Antrieb
     - Antr
     - Diesel
   * - Segment
     - Segm
     - RigidTruck >12-14t (Diesel)
   * - Baujahr
     - BJ
     - 2010
   * - Emissionsstandards
     - ES
     - Euro-V
   * - Attribut
     - Attr
     - SCR, DPF
   * - Fahrzeugschicht
     - FS
     - RT >12-14t Euro-V SCR
   * - Konzept
     - Konz
     - HDV diesel Euro-5 SCR (DPF)

Abkürzungen: SCR: Selektive Catalytic Reduktion, EGR: Exhaust Gas Recirculation, zGG: zulässiges Gesamtgewicht

TREMOD verwendet eine Vielzahl an verschiedenen **Eingangsdaten**. Ein Teil der Eingangsdaten wird standardmäßig
für die Fortschreibung des Inventars und des Trendszenarios aktualisiert, andere Eingangsdaten können bei Bedarf,
z.B. im Fall von methodischen Weiterentwicklungen aktualisiert werden. Folgende Tabelle gibt hierzu eine Übersicht.

.. list-table:: **Übersicht Eingangsdaten Straße und Aktualisierungsturnus**
   :widths: 30 80 80
   :header-rows: 1

   * - Modul
     - Jährlich (Inventar + Trendszenario)
     - Bei Bedarf
   * - Allgemein
     - Energiebilanzdaten, Anteil Biokraftstoffe
     - Heizwerte, Dichten
   * - Bestand
     - Realbestände KBA, Bestände Mopeds und Pedelces, Neuzulassungen (NZL), NZL-Anteil Segment, NZL-Anteil Emissionsstandard
     - Anteil EGR/SCR, Anteil Partikelfilter, Anteil High-Emitter, Anteil Softwareupdates
   * - Fahrleistung
     - Fahrleistungen pro Fahrzeugkategorie, Anteil Straßenkategorie
     - Fahrleistungsgewichtung Segment, Fahrleistungsgewichtung Alter
   * - Verkehrsleistung
     - Verkehrsleistungen pro Verkehrsart
     - Auslastungsgrade Segment
   * - Emissionen
     - CO2-Intensität Kraftstoffe, jährliche Effizienzverbesserung
     - Emissionsfaktoren HBEFA

In den folgenden Abschnitten zur Berechnung wird auf die jeweiligen Eingangsdaten vertieft eingegangen.

1.1 Bestände
~~~~~~~~~~~~~~~~~~
Im Bestands-Modul werden die Realbestände des KBA um zusätzliche Merkmale der Emissionsberechnung
(z.B. Abgasnachbehandlung) erweitert und auf Basis von jährlichen Neuzulassungen und Überlebenskurven für das
Trendszenarios bis 2050 fortgeschrieben. Ergebnis ist der Fahrzeugbestand nach Fahrzeugschicht für
die Bezugsjahre 1950 bis 2050.

Der **Realbestand** wird aus einer Sonderauswertung des Kraftfahrtbundesamtes (KBA) ermittelt. Diese umfasst den Bestand
zum 1.1. des Jahres für Deutschland insgesamt nach verschiedenen Merkmalen,
z.B. Fahrzeugkategorie, Antrieb, Größenklasse (z.B. zul. Gesamtgewicht) Erstzulassungsjahr, Emissionsklasse.

Die Anfrage wird per E-Mail an fahrzeugstatistik@kba.de gestellt und erfolgt im Rahmen der Amtshilfe.
Die Daten müssen **vor der Verwendung in TREMOD aufbereitet** werden:

* Berechnung des Bestandes zur Jahresmitte aus dem Bestand zum 1.1. des Bezugsjahres und dem 1.1. des Folgejahres zur Ableitung eines repräsentativen Fahrzeugbestandes für das ganze Bezugsjahr (Im Gegensatz zu einem Bestand zu einem Stichtag, z.B. 1.7. werden somit auch ungleiche Änderungen innerhalb der 1. und 2. Jahreshälfte erfasst. Beispielsweise wurden Elektro-Pkw bisher stärker gegen Jahresende zugelassen)
* Neuzuordnung der Fahrzeugkategorien, z.B. "Lastkraftwagen" in LNF (3,5 t zGG) und LKW (>= 3,5 t zGG)
* Neuzuordnung nicht verwendeter Antriebsarten, z.B. "Vielstoff" zu "Diesel"
* Zusammenfassung von Fahrzeugen mit einem Alter von mehr als 60 Jahren zu 60 Jahren.
* Zuordnung der Emissionsstandards über die Emissionsklasse und das Erstzulassungsjahr inklusive Neuzuordnung unplausibler Emissionsstandards, z.B. Euro 1 Baujahr 2010 zu Euro 5.


Anschließend wird in TREMOD der Bestand nach Fahrzeugkategorie, Antrieb, Erstzulassungsjahr und Emissionsstandard
um weitere **Attribute** ergänzt:

* Anteil Partikelfilter Diesel-Pkw und Busse je Baujahr
* Anteil EGR und SCR bei Bussen und schweren Nutzfahrzeugen mit Euro IV und V
* Anteil Euro 5- und Euro 6 Diesel-Pkw mit Softwareupdates je Bezugsjahr
* Anteil High-Emitters für Busse und schweren Nutzfahrzeuge mit Euro V, VI und 7

Die Berechnung erfolgt multiplikativ mit den jeweiligen Anteilen zum Fahrzeugbestand.

Für das **Trendszenario** werden jährlichen Neuzulassungen nach Fahrzeugschicht und die Überlebenskurven benötigt.
Die jährlichen Neuzulassungen berechnen sich aus aus dem Produkt folgender Werte:

* AbsolutenNeuzulassungen je Fahrzeugkategorie
* Anteil Segmente je Fahrzeugkategorie
* Anteil Emissionsstandards je Segment und Zulassungsjahr

Die Neuzulassungen und Neuzulassungsanteile werden auf Basis von Annahmen, z.B. Erfüllung der
CO2-Flottenzielwerte und Schadstoffemissionsgrenzwerte festgelegt.

Die Überlebenskurven beschreiben das Verhältnis der neuzugelassenen Fahrzeuge zum verbleibenden Bestand für das
Fahrzeugalter von 0-60 Jahre. Für die Fortschreibung wird das Verhältnis des verbleibenden Bestands des jeweiligen
Bezugsjahres zum Vorjahr berechnet, damit auch der Bestand der Fahrzeuge im Realbestand fortschrieben werden kann.

**Ablaufdiagramm Bestandsberechnung**

.. image:: images/Ablaufdiagramm_Road_Bestand.png

Abkürzungen: Fzkat: Fahrzeugkategorie, Segm: Segment, ES: Emissionsstandard, BJ: Baujahr, FS: Fahrzeugschicht, SCR:
Selektive Catalytic Reduktion, EGR: Exhaust Gas Recirculation, DPF: Diesel Particle Filter, Trend: Trendszenario

1.2 Fahrleistungen
~~~~~~~~~~~~~~~~~~
Im Fahrleistungsmodul werden jährliche Fahr- und Verkehrsleistungen je nach Fahrzeugschicht, Baujahr, Energie und
Straßenkategorie sowie die mittlere kumulierte (Lebens-)Fahrleistung je Fahrzeugsegment (Größenklasse und Antrieb) berechnet.

Für die Fahrleistungen werden zunächst die **Gesamtfahrleistungen** je Fahrzeugkategorie und Bezugsjahr auf die
Straßenkategorien aufgeteilt.
Die Eingangsdaten für Realjahre werden aus verschiedenen Erhebungen, z.B. der Bundesanstalt für Straßenwesen (BASt),
dem Kraftfahrtbundesamt (KBA), dem Bundesamt für Logistik und Mobilität (BALM) oder
dem statistischen Bundesamt (DESTATIS) zusammengestellt und für TREMOD aufbereitet. Die Ergebnisse werden soweit
möglich mit der Erhebung Verkehr in Zahlen (VIZ) des Bundesministeriums für Verkehr (BMV) abgeglichen.
Hierbei ist jedoch zu erwähnen, dass TREMOD die Inlandsfahrleistungen und VIZ die Inländerfahrleistungen ausweist.

Anschließend erfolgt auf Basis der Bestandsanteile und von Gewichtungsfaktoren nach Segment und Alter die Berechnung
der **Fahrleistung pro Straßenkategorie, Fahrzeugschicht, Baujahr und Energieart**.
Die Eingangsdaten für die Gewichtungsfaktoren stammen aus verschiedenen Quellen, z.B. der Fahrleistungserhebung der BASt.
Weitere Informationen sind in den jeweils aktuellen TREMOD-Berichten dokumentiert.

**Ablaufdiagramm Fahrleistungsberechnung**

.. image:: images/Ablaufdiagramm_Road_Fahrleistung.png

Abkürzungen: Fzkat: Fahrzeugkategorie, Segm: Segment, ES: Emissionsstandard, BJ: Baujahr, FS: Fahrzeugschicht, SK:
Straßenkategorie, En: Energieart)

Die **kumulierten Fahrleistungen** werden in zwei Schritten berechnet:
   * Berechnung der mittlere Jahresfahrleistungen je Fahrzeugsegment und Baujahr (Fahrleistung dividiert durch Bestand)
   * Aufkumulierung der mittleren Jahresfahrleistungen seit der Erstzulassung

Die **Verkehrsleistungen** werden mithilfe der spezifischen Kapazität je Segment (z.B. Zuladung in Tonnen oder Sitzplätze) und
mittleren Auslastungsgraden zunächst bottom-up berechnet. Anschließend werden die Auslastungsgrade so kalibriert, dass
die vorgegebene Verkehrsleistung je Verkehrsart getroffen wird und die Berechnung erneut durchgeführt.

1.3 Energieverbrauch und Emissionen
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Die Berechnung des Energieverbrauchs und der Emissionen basiert auf der Methodik des Handbuch Emissionsfaktoren für den
Straßenverkehr (HBEFA). Es wird zwischen Warm (hot)-, Kaltstart (coldstart)- und Verdungstungs(Evaporation)-Emissionen
unterschieden, welche unterschiedliche Aktivitätsdaten und Emissionsfaktoren verwenden.
Detaillierte Informationen zum HBEFA finden sich unter www.hbefa.net.

Die **Warmemissionen** (warm emissions) werden pro Fahrzeugschicht, Baujahr, Energieart und Straßenkategorie berechnet.
Hierbei werden die Emissionsfaktoren pro Kilometer mit der Fahrleistung verknüpft. Die Einheit der Emissionen wird
in den folgenden Formeln beispielhaft in g angegeben, kann aber je nach Schadstoff variieren, z.B. MJ für
Energieverbrauch, # für Partikelanzahl.

.. raw:: html

   <div style="border: 1px solid black; padding: 10px; margin: 10px;">
      Warmemissionen (g/km) = Fahrleistung (km) x Basisemissionsfaktor (g/km)
   </div>

*Differenzierung: Fahrzeugschicht, Energieart, Straßenkategorie, Schadstoff. Anmerkung: mit Basisemissionsfaktor sind hier die ungewichteten Emissionsfaktoren je Fahrzeugschicht (im HBEFA "Subsegment") gemeint. Diese beziehen sich z.B. auf eine kumulierte Fahrleistung von 50.000 km.*

Anschließend werden auf die Basisemissionsfaktoren je nach Fahrzeugkategorie und Schadstoff verschiedene Korrekturfaktoren
angewendet. Folgende Tabelle gibt hierzu einen Überblick:

.. list-table:: **Einflussfaktoren und Parameter**
   :widths: 25 25 25 25 25
   :header-rows: 1

   * - Faktor
     - Abhängige Parameter
     - Schadstoffe
     - Fahrzeugkategorie
     - Anwendung zum Basisemissionsfaktor
   * - Energieeffizienz
     - Baujahr
     - EC
     - alle
     - multiplikativ
   * - Verschlechterungsfaktor
     - kumulierte Fahrleistung
     - HC, CO, NOx, PM10-ex, CH4, N2O, NH3, N2O
     - Pkw, LNF, Lkw, LZ, SZ, LBus, ÜeKfzl, Üekfzs, FlBus, SRbus
     - additiv
   * - Auslastungskorrektur
     - mittlere Beladung
     - alle
     - Lkw, LZ, SZ, LBus, Üekfzs, FlBus, SRbus
     - lineare interpolation (0%,50%,100% Beladung)
   * - Kraftstoffqualität
     - Bezugsjahr
     - HC, CO, NOx, PM10-ex
     - alle
     - multiplikativ

Die Berechnung der N2O und NH3 Emissionen wird wie im HBEFA gemäß der Methode des COPERT-Modells nachgebildet und
berücksichtigt zusätzlich den Schwefelgehalt im Kraftstoff.

Die **Kaltstartemissionen** berechnen sich aus der Anzahl der Kaltstarts und den mittleren Emissionsfaktoren pro Start je
Fahrzeugschicht. Die Anzahl der Starts wird aus der Fahrleistung und der mittleren Wegelänge je Fahrzeugkategorie/-Segment
berechnet.

.. raw:: html

   <div style="border: 1px solid black; padding: 10px; margin: 10px;">
      Kaltstartemissionen/Energieverbrauch (g) = Anzahl starts (-) x Emissionsfaktor (g/Start)
   </div>

*Differenzierung:  Fahrzeugschicht, Energieart, Schadstoff*

Die **Verdunstungsemissionen** berechnen sich je nach Art der Verdunstung aus dem Bestand (soak emissions), der Fahrleistung
(running losses) und der Anzahl Starts (diurnal).
*Anm: Verdunstungsemissionen treten nur für Nicht-Methan-Kohlenwasserstoffe (NMHC) und deren Komponenten auf. Der Energieverbrauch und sonstige Schadstoffe sind nicht betroffen.*

.. raw:: html

   <div style="border: 1px solid black; padding: 10px; margin: 10px;">
      Abstellemissionen (g) = Anzahl stopps (-) x Emissionsfaktor (g/Stopp)
   </div>

*Differenzierung: Fahrzeugschicht, Energieart, Schadstoff*

(Die Anzahl der Stops wird gleich der Anzahl der Starts angenommen, siehe Kaltstartemissionen).

.. raw:: html

   <div style="border: 1px solid black; padding: 10px; margin: 10px;">
      Tankatmung (g) = Anzahl Fahrzeuge (-) x 365 (d) x Emissionsfaktor (g/Fahrzeug/d)
   </div>

*Differenzierung:* Fahrzeugschicht, Energieart, Schadstoff

.. raw:: html

   <div style="border: 1px solid black; padding: 10px; margin: 10px;">
      Running Losses (g) = Fahrleistung (km) x Emissionsfaktor (g/km)
   </div>

*Differenzierung: Fahrzeugschicht, Energieart, Straßenkategorie, Schadstoff*

Zusätzlich finden folgende Schritte für **abgeleitete Emissionen** statt:
   * die Aufteilung aller Emissionen nach fossilen und Biokraftstoffen
   * die Berechnung der kraftstoffverbrauchsabhängigen Emissionen (CO2, SO2, Pb)
   * Berechnung der Emissionen von HC-Komponenten (z.B. CH4, NMHC)
   * Berechnung von NO2-Emissionen aus den NOx-Emissionen
   * Berechnung von CO2-Äquivalenten
   * Berechnung von Black-Carbon Emissionen

Die **Aufteilung in fossile und Biokraftstoffe** erfolgt über die Anteilsfaktoren je Energieart und Bezugsjahr. Sie wird
für alle Größen (Fahrleistungen, Energieverbrauch, Emissionen) durchgeführt.
Die Eingangsdaten für die Biokraftstoffanteile stammen aus der amtlichen Mineralölstatistik (AMS) des BAFA. Im Trendszenario
werden Annahmen zum Biokraftstoffeinsatz, z.B. zur Einhaltung gesetzlicher Quoten, getroffen.

.. raw:: html

   <div style="border: 1px solid black; padding: 10px; margin: 10px;">
      Emissionen_Energie (g) = Emissionen_Energie_Bezug (g) x Anteil_Energie/Energie_Bezug (%)
   </div>

*Differenzierung:  Bezugsjahr, Energieart, Verkehrsträger*

Die **CO2-Emissionen** werden mithilfe des Energieverbrauchs und spezifischer CO2-Emissionsfaktoren (kg/TJ) je
Energieart berechnet.
Die Emissionsfaktoren werden jährlich vom Umweltbundesamt aktualisiert und für TREMOD zur Verfügung gestellt.
Die Werte für SO2 und Pb sind in den TREMOD-Berichten beschrieben. Die folgende Formel veranschaulicht die Berechnung
am Beispiel CO2.

.. raw:: html

   <div style="border: 1px solid black; padding: 10px; margin: 10px;">
      CO2-Emissionen (kg) = Energieverbrauch (TJ) x Emissionsfaktor (kg/TJ)
   </div>

*Differenzierung:  Bezugsjahr, Energieart, Verkehrsträger*

Die Schadstoffe **CH4, NMHC, Benzol, Toluol, Xylol** werden als Anteile von HC, welche mit den HC-Emissionen multipliziert
werden berechnet. Die HC-Anteile stammen aus dem HBEFA. Die folgende Formel veranschaulicht die Berechnung
am Beispiel CH4.

.. raw:: html

   <div style="border: 1px solid black; padding: 10px; margin: 10px;">
      CH4-Emissionen (g) = HC-Emissionen (g) x Anteil CH4/HC (%)
   </div>

*Differenzierung:  Konzept, Emissionsart*

Die **NO2-Emissionen** werden als Anteile von NOx, welche mit den NOx-Emissionen multipliziert
werden, berechnet. Die NO2-Anteile stammen aus dem HBEFA.

.. raw:: html

   <div style="border: 1px solid black; padding: 10px; margin: 10px;">
      NO2-Emissionen (g) = NOx-Emissionen (g) x Anteil NO2/NOx (%)
   </div>

*Differenzierung:  Konzept, kumulierte Fahrleistung, Straßenkategorie*

1.4 Energiebilanzkorrektur und ZSE-Ausgabe
~~~~~~~~~~~~~~~~~~~~~~~~~~
TREMOD berechnet die Energieverbräuche des Verkehrs bottom-up auf Grundlage von Beständen, Fahrleistungen und spezifischen
Emissionsfaktoren. Für die Berichterstattung des Umweltbundesamtes sind jedoch die offiziell gemeldeten Kraftstoffabsätze
im Verkehr relevant, welche jährlich von der Arbeitsgemeinschaft Energiebilanzen (AGEB) erstellt werden.
Daher wird in TREMOD eine **Energiebilanzkorrektur** durchgeführt. Diese erfolgt in Form von Korrekturfaktoren, welche auf
den Energieverbrauch und die Emissionen angewendet werden. Bestände und Fahrleistungen werden nicht korrigiert.
Folgende Formel veranschaulicht die Berechnung am Beispiel des Benzinverbrauchs.

.. raw:: html

   <div style="border: 1px solid black; padding: 10px; margin: 10px;">
      Benzinverbrauch_korrigiert (MJ) = Benzinverbrauch (MJ) x Korrekturfaktor (-)
   </div>

*Differenzierung:  Verkehrsträger, Fahrzeugkategorie, Energieart, Bezugsjahr*

Für die Unterscheidung nach Fahrzeugkategorie und Energieart wird wie folgt vorgegangen:
   * Die Korrekturfaktoren für Benzin-Pkw, Benzin-LNF und MZR werden direkt aus dem Verhältnis des Benzinabsatzes laut Energiebilanz zum berechneten Benzinverbrauch für alle Fahrzeugkategorien in TREMOD berechnet.
   * Die Korrekturfaktoren für Diesel-Pkw und Diesel-LNF werden von Benzin-Pkw und Benzin-LNF übernommen.
   * Die Korrekturfaktoren für SNF und Busse werden aus der Restmenge des Dieselabsatzes (Dieselabsatz ingesamt - Dieselabsatz Pkw+LNF) im Verhältnis zum berechneten Dieselverbrauch der SNF und Busse berechnet.
   * Für alle sonstigen Energiearten werden die Korrekturfaktoren über das Verhältnis von Absatz zu Verbrauch ermittelt, unabhängig von der Fahrzeugkategorie.
   * Falls keine Energiebilanzdaten für eine Energieart vorliegen oder diese für die Berichterstattung nicht relevant sind, wird als Korrekturfaktor 1 verwendet

Die hierbei berechneten Korrekturfaktoren werden auch für die Emissionen angewendet.

Die korrigierten Energieverbrauchsdaten bilden auch die Grundlage für die nationale Berichterstattung im
**zentralen System Emissionen (ZSE)**. TREMOD verfügt hierzu über eine eigene ZSE-Schnittstelle für den Verkehr.

Das ZSE unterscheidet im Straßenverkehr nach Fahrzeugkategorie, Kraftstoffart, Emissionsstandard, Emissionsart,
Straßenkategorie und Bezugsjahr. Dabei wird jedoch eine aggregierte Datenform und eine eigene Nomenklatur verwendet,
welche in entsprechenden Zuordnungstabellen hinterlegt ist. Auch wird nur ein Teil der in TREMOD verfügbaren Schadstoffe für das ZSE berichtet.

Das ZSE beinhaltet folgende Kenngrößen:
   * Aktivitätsrate: für direkte Emissionen in Terajoule (TJ), für Verdunstungsemissionen in Tonnen (t) Kraftstoff
   * Emissionsfaktoren: für direkte Emissionen in kg/TJ, für Verdunstungsemissionen in kg/t Kraftstoff

Die Emissionsfaktoren berechnen sich aus dem Quotient aus den Emissionen und dem Endenergieverbrauch je Bezugsjahr und
ZSE-Kategorie.

2. Implementierung
------------------
Der Quellcode für sämtliche Abfragen und Berechnungen von TREMOD erfolgt in Python und die Datenhaltung in mehreren
PostgreSQL-Datenbanken. Im folgenden werden die Datenschnittstellen, Eingangsdatenformate und Berechnungschritte
skizziert.

2.1 Datenschnittstellen
~~~~~~~~~~~~~~~~~~~~~~~
Alle Eingangsdaten und Definitionen sind als Tabellen in der SQL-Datenbank gespeichert und können dort verändert werden,
z.B. für jährliche Updates. Sie werden über das Modul tableoperations aufgerufen und in die Berechnungen für TREMOD-Road
integriert. Der Name der Datenbank setzt sich aus "tremod_road" + "Versionsnummer" zusammen.

Alle verwendeten Tabellen werden im Modul **tableoperations.py** und der Klasse **PersistanceLayer** aufgelistet.
Sie beinhaltet folgende Methoden, welche im folgenden genauer beschrieben werden:

**get_common**

**get_definitions**

**get_stock_data**

**get_milage_data**

**get_emission_factors**

Die Methoden **get_results** und **write_to_db** dienen dem Lesen und Schreiben der Ergebnisse
zu Bestand, Fahr- und Verkehrsleistung und Emissionen in die Datenbank.

2.2 Eingangsdaten
~~~~~~~~~~~~~~~~~~
Die aktuellen Datenquellen sind in den UBA-Berichten zur TREMODD-Aktualisierung dokumentiert. Daher wird nur auf
die wichtigsten Tabellen eingegangen, welche im Rahmen der jährlichen Updates angepasst werden.

**Common data**


Tabellen:

.. include:: tables/common.rst

**Defintions**


Tabellen:

.. include:: tables/definitions.rst

**Stock**

Tabellen:

.. include:: tables/stock.rst

**Mileage**

Tabellen:

.. include:: tables/mileage.rst

**Emissions**

Tabellen:

*Hinweis: Erläuterungen zu den Spalten sind im HBEFA bzw. inder HBEFA-Dokumentation zu finden*

.. include:: tables/emissions.rst

2.3 Berechnungen
~~~~~~~~~~~~~~~~~~
Im folgenden werden die Berechnungsschritte der Module stock, mileage, emissions und results vereinfacht
dargestellt.

Die Module verfügen über verschiedene Klassen (class), welche wiederum verschiedene Methoden beinhalten.
Jede Klasse und Methode verfügt über eine Kurzbeschreibung sowie ein Liste der Variablen und Ausgabeparameter.

**stock**

Code-Beschreibung:

.. automodule:: road.src.stock
   :no-index:
   :members:
   :undoc-members:
   :inherited-members:
   :show-inheritance:

*Flow-Chart Module Stock*

.. image:: images/PAP_Road_stock.svg

**Mileage**

Code-Beschreibung:

.. automodule:: road.src.milage
   :no-index:
   :members:
   :undoc-members:
   :inherited-members:
   :show-inheritance:

*Flow-Chart Module Mileage*

.. image:: images/PAP_Road_milage.svg

**emissions**

Code-Beschreibung:

.. automodule:: road.src.emissions
   :no-index:
   :members:
   :undoc-members:
   :inherited-members:
   :show-inheritance:

*Flow-Chart Module Emissions*

.. image:: images/PAP_Road_emissions.svg

**results**

Code-Beschreibung:

.. automodule:: road.src.results

.. autoclass:: TremodDevelVariant
   :no-index:
   :members:
   :undoc-members:
   :inherited-members:
   :show-inheritance:

*Flow-Chart Module Results*

.. image:: images/PAP_Road_results.svg

2.4 HBEFA-API
~~~~~~~~~~~~~~~~~

Das Modul `hbefa_api` dient der automatisierten Abfrage von Emissionsfaktoren über die offizielle HBEFA-Schnittstelle (API). Es ermöglicht den Abruf strukturierter Datensätze mit Emissionsfaktoren des Straßenverkehrs und deren Integration in den TREMOD-Road-Workflow.

Es werden fünf Abfragen konfiguriert und durchgeführt, um die Tabellen mit Emissionsfaktoren (hot, cold, soak, diurnal, running losses)
zu erzeugen (siehe Tabellen bei **Emissions**).
Hierzu müssen Nutzername und Passwort für eine gültige HBEFA-Lizenz daten vorliegen. Diese Daten dürfen im Rahmen
einer einfachen Lizenz für das UBA verwendet werden.

Die wichtigsten zu definierenden Abfrageparameter für die Tabellen der Emissionskategorien hot, coldstart , dirunal, soak
und running losses sind:

   * weighting (Flottengewichtete oder -ungewichtete Emissionsfaktoren)
   * country (Land. Wichtig für Länderspezifische Daten)
   * emcat (Emissionskategorie, z.B. "hot", "cold")
   * pollutant (Schadstoff)
   * agglevel_fleet (Differenzierung nach Fahrzeugeigenschaft. IdR. nach Fahrzeugschicht, d.h. "subsegment")
   * agglevel_ts (Individuelle oder aggregierte Verkehrssituationen)
   * idvehcat (Fahrzeugkategorie)
   * lang (Sprache)
   * idtraffic_scen (Länderspezifisches Szenario, z.B. für Flottenzusammensetzung)
   * idtsgrad (Auswahl Verkehrssituationen)
   * idpatternambientcond (Auswahl Umgebungsbedingungen, z.B. Temperaturverteilungen)
   * nocorr (Verwendung Basis-Emissionsfaktoren aus PHEM oder korrigierte Emissionsfaktoren, z.B. um Temperatur)
   * hbversion_int (Nummer HBEFA-Version)

Die Abfrage der Emissionsfaktorentabellen erforlgt nicht bei jedem Rechenlauf zur Bestimmung der Emissionen des
Straßenverkehrs, sondern muss bei Bedarf beispielsweise wegen folgender Gründe aktiv ausgeführt werden:

 - Update der TREMOD-Version und sich zwischenzeitlicher veränderter HBEFA-Version
 - Aktualisierungen des HBEFA, die in eine bestehende TREMOD-Version einfließen sollen
 - Erweiterung der TREMOD-Berechnungen (z.B. weitere Schadstoffe)

**Wichtigste Dateien und Funktionen:**

*   `hbefapi.py`: Enthält die Klasse `HBEFapi`, welche die technische Kommunikation mit der API übernimmt (Login-Management, CSRF-Token-Extraktion, asynchrone Abfragen und Status-Polling).
*   `dataset.py`: Beinhaltet die Klasse `HBEFADatasetManager`. Dies ist die zentrale Steuerungseinheit, welche die API initialisiert, Abfragen orchestriert und die Ergebnisse persistiert. Sie bietet zudem eine CLI-Schnittstelle via `typer`.
*   `config.py`: Zentrale Konfigurationsdatei für Abfrageparameter (z. B. HBEFA-Version, Land, Schadstoffe) und Dateipfade.
*   `write2postgres.py`: Skript zur Übertragung der lokal in SQLite-Datenbanken zwischengespeicherten Ergebnisse in die PostgreSQL-Datenbank von TREMOD.
*   `credentials.py`: Speichert die API-Zugangsdaten (URL, Benutzername, Passwort). Diese Datei ist lokal zu pflegen und sollte nicht in das Repository eingehen.

**Konfiguration und Durchführung der Abfragen:**

Die Abfragen werden primär über die `config.py` gesteuert. Hier werden in der Dictionary `HBEFA2TREMOD_TABLES` die gewünschten Tabellen (z. B. `hot`, `coldstart`, `evap`) und deren Parameter (Schadstoffe, Fahrzeugkategorien, Aggregationslevel) definiert.

Die Durchführung erfolgt durch Ausführen der `dataset.py` des Moduls, beispielsweise über die Befehlszeile:

.. code-block:: bash

    python dataset.py --run-hbefa2tremod-tables --write-to-db

Dabei werden asynchrone Tasks am HBEFA-Server gestartet, deren Status regelmäßig abgefragt wird. Nach Abschluss werden die Ergebnisse standardmäßig in einer SQLite-Datenbank unter `road/data/hbefa/raw/` abgelegt.

**Abruf von Definitionstabellen:**

Zusätzlich zu den Emissionsfaktoren können auch die Definitions- bzw. Parametertabellen der API (z. B. Listen der verfügbaren Schadstoffe, Fahrzeugkategorien, Verkehrssituationen) abgerufen werden. Dies ist hilfreich, um die gültigen Parameterwerte für die Konfiguration in `config.py` zu ermitteln. Der Abruf erfolgt durch Setzen des Flags `--get-definition-tables True`:

.. code-block:: bash

   python dataset.py --get-definition-tables --write-to-db

Diese Tabellen werden in einer separaten SQLite-Datenbank namens `dataset_param_tables_[ZEITSTEMPEL].db` im Verzeichnis `road/data/hbefa/raw/` gespeichert.

**Datenhaltung und Transfer:**

Die Ergebnisse der Emissionsfaktor-Abfragen werden zunächst lokal in SQLite-Datenbanken unter `road/data/hbefa/raw/` gespeichert (Dateiname: `dataset_[QUERY]_[ZEITSTEMPEL].db`). Dies dient der Entkopplung von der API und den Hauptdatenbanken.

Für die Verwendung in TREMOD-Road müssen diese Daten mit dem Skript `write2postgres.py` in die PostgreSQL-Datenbank übertragen werden. Nach einem erfolgreichen API-Abruf sind im Skript `write2postgres.py` folgende Einstellungen zu prüfen bzw. anzupassen:

*   `DATE_OF_CALL`: Zur Bestimmung des Pfad zur lokalen SQLite-Datenbank, die die gewünschten abgerufenen Daten enthält.
*   `SUFFIX_4_POSTGRES`: Ein optionales Suffix für die Tabellennamen (z. B. `_hb501006` oder `_hb521111_test`), um verschiedene HBEFA-Stände in der Datenbank parallel vorhalten zu können.

Das Skript liest die Tabellen aus den SQLite-Datenbanken und schreibt in die entsprechenden Postgres-Tabellen
(z. B. für Emissionsfaktoren warm oder Kaltstart).
Hierbei wird die in der TableOperations.py definierte Datenbank als Zieldatenbank verwendet.

**Logging:**

Das Modul unterstützt ein detailliertes Logging. Die Log-Dateien werden unter `road/data/hbefa/logs/` mit Zeitstempel abgelegt (z. B. `dataset_2026-06-26_09-52-00.log`).
Geloggt werden:

*   Erfolg oder Fehler beim Login.
*   Start von asynchronen Tasks inkl. Task-IDs.
*   Status-Updates während des Pollings.
*   Detaillierte Fehlermeldungen der API im Falle von ungültigen Parametern.
*   Erfolgreiche Schreibvorgänge in Dateien oder Datenbanken.

**Ablaufschéma einer Abfrage:**

.. image:: images/hbefa_api_flow.svg
   :width: 200px
   :align: center

