pycontrails 0.58.0__cp314-cp314-win_amd64.whl

pycontrails/core/flightplan.py

@@ -0,0 +1,228 @@
+"""ATC Flight Plan Parser."""
+
+import re
+from typing import Any
+
+
+def to_atc_plan(plan: dict[str, Any]) -> str:
+    """Write dictionary from :func:`parse_atc_plan` as ATC flight plan string.
+
+    Parameters
+    ----------
+    plan: dict[str, Any]
+        Dictionary representation of ATC flight plan returned from :func:`parse_atc_plan`.
+
+    Returns
+    -------
+    str
+        ATC flight plan string conforming to ICAO Doc 4444-ATM/501
+
+    See Also
+    --------
+    :func:`parse_atc_plan`
+    """
+    ret = f"(FPL-{plan['callsign']}-{plan['flight_rules']}"
+    ret += f"{plan['type_of_flight']}\n"
+    ret += "-"
+    if "number_aircraft" in plan and plan["number_aircraft"] <= 10:
+        ret += plan["number_aircraft"]
+    ret += f"{plan['type_of_aircraft']}/{plan['wake_category']}-"
+    ret += f"{plan['equipment']}/{plan['transponder']}\n"
+    ret += f"-{plan['departure_icao']}{plan['time']}\n"
+    ret += f"-{plan['speed_type']}{plan['speed']}{plan['level_type']}"
+    ret += f"{plan['level']} {plan['route']}\n"
+    if "destination_icao" in plan and "duration" in plan:
+        ret += f"-{plan['destination_icao']}{plan['duration']}"
+    if "alt_icao" in plan:
+        ret += f" {plan['alt_icao']}"
+    if "second_alt_icao" in plan:
+        ret += f" {plan['second_alt_icao']}"
+    ret += "\n"
+    ret += f"-{plan['other_info']}"
+    if "supplementary_info" in plan:
+        ret += "\n-"
+        ret += " ".join([f"{i[0]}/{i[1]}" for i in plan["supplementary_info"].items()])
+
+    ret += ")"
+
+    if ret[-1] == "\n":
+        ret = ret[:-1]
+
+    return ret
+
+
+def parse_atc_plan(atc_plan: str) -> dict[str, str]:
+    """Parse an ATC flight plan string into a dictionary.
+
+    The route string is not converted to lat/lon in this process.
+
+    Parameters
+    ----------
+    atc_plan : str
+        An ATC flight plan string conforming to ICAO Doc 4444-ATM/501 (Appendix 2)
+
+    Returns
+    -------
+    dict[str, str]
+        A dictionary consisting of parsed components of the ATC flight plan.
+        A full ATC plan will contain the keys:
+
+        - ``callsign``: ICAO flight callsign
+        - ``flight_rules``: Flight rules ("I", "V", "Y", "Z")
+        - ``type_of_flight``: Type of flight ("S", "N", "G", "M", "X")
+        - ``number_aircraft``: The number of aircraft, if more than one
+        - ``type_of_aircraft``: ICAO aircraft type
+        - ``wake_category``: Wake turbulence category
+        - ``equipment``: Radiocommunication, navigation and approach aid equipment and capabilities
+        - ``transponder``: Surveillance equipment and capabilities
+        - ``departure_icao``: ICAO departure airport
+        - ``time``: Estimated off-block (departure) time (UTC)
+        - ``speed_type``: Speed units ("K": km / hr, "N": knots)
+        - ``speed``: Cruise true airspeed in ``speed_type`` units
+        - ``level_type``: Level units ("F", "S", "A", "M")
+        - ``level``: Cruise level
+        - ``route``: Route string
+        - ``destination_icao``: ICAO destination airport
+        - ``duration``: The total estimated elapsed time for the flight plan
+        - ``alt_icao``: ICAO alternate destination airport
+        - ``second_alt_icao``: ICAO second alternate destination airport
+        - ``other_info``: Other information
+        - ``supplementary_info``: Supplementary information
+
+    References
+    ----------
+    - https://applications.icao.int/tools/ATMiKIT/story_content/external_files/story_content/external_files/DOC%204444_PANS%20ATM_en.pdf
+
+    See Also
+    --------
+    :func:`to_atc_plan`
+    """
+    atc_plan = atc_plan.replace("\r", " ")
+    atc_plan = atc_plan.replace("\n", " ")
+    atc_plan = atc_plan.upper()
+    atc_plan = atc_plan.strip()
+
+    if len(atc_plan) == 0:
+        raise ValueError("Empty or invalid flight plan")
+
+    atc_plan = atc_plan.replace("(FPL", "")
+    atc_plan = atc_plan.replace(")", "")
+    atc_plan = atc_plan.replace("--", "-")
+
+    basic = atc_plan.split("-")
+
+    flightplan: dict[str, Any] = {}
+
+    # Callsign
+    if len(basic) > 1:
+        flightplan["callsign"] = basic[1]
+
+    # Flight Rules
+    if len(basic) > 2:
+        flightplan["flight_rules"] = basic[2][0]
+        flightplan["type_of_flight"] = basic[2][1]
+
+    # Aircraft
+    if len(basic) > 3:
+        aircraft = basic[3].split("/")
+        matches = re.match(r"(\d{1})(\S{3,4})", aircraft[0])
+        groups = matches.groups() if matches else ()
+
+        if matches and len(groups) > 2:
+            flightplan["number_aircraft"] = groups[1]
+            flightplan["type_of_aircraft"] = groups[2]
+        else:
+            flightplan["type_of_aircraft"] = aircraft[0]
+
+        if len(aircraft) > 1:
+            flightplan["wake_category"] = aircraft[1]
+
+    # Equipment
+    if len(basic) > 4:
+        equip = basic[4].split("/")
+        flightplan["equipment"] = equip[0]
+        if len(equip) > 1:
+            flightplan["transponder"] = equip[1]
+
+    # Dep. airport info
+    if len(basic) > 5:
+        matches = re.match(r"(\D*)(\d*)", basic[5])
+        groups = matches.groups() if matches else ()
+
+        if groups:
+            flightplan["departure_icao"] = groups[0]
+        if len(groups) > 1:
+            flightplan["time"] = groups[1]
+
+    # Speed and route info
+    if len(basic) > 6:
+        matches = re.match(r"(\D*)(\d*)(\D*)(\d*)", basic[6])
+        groups = matches.groups() if matches else ()
+
+        # match speed and level
+        if groups:
+            flightplan["speed_type"] = groups[0]
+            if len(groups) > 1:
+                flightplan["speed"] = groups[1]
+            if len(groups) > 2:
+                flightplan["level_type"] = groups[2]
+            if len(groups) > 3:
+                flightplan["level"] = groups[3]
+
+            flightplan["route"] = basic[6][len("".join(groups)) :].strip()
+        else:
+            flightplan["route"] = basic[6].strip()
+
+    # Dest. airport info
+    if len(basic) > 7:
+        matches = re.match(r"(\D{4})(\d{4})", basic[7])
+        groups = matches.groups() if matches else ()
+
+        if groups:
+            flightplan["destination_icao"] = groups[0]
+        if len(groups) > 1:
+            flightplan["duration"] = groups[1]
+
+        matches = re.match(r"(\D{4})(\d{4})(\s{1})(\D{4})", basic[7])
+        groups = matches.groups() if matches else ()
+
+        if len(groups) > 3:
+            flightplan["alt_icao"] = groups[3]
+
+        matches = re.match(r"(\D{4})(\d{4})(\s{1})(\D{4})(\s{1})(\D{4})", basic[7])
+        groups = matches.groups() if matches else ()
+
+        if len(groups) > 5:
+            flightplan["second_alt_icao"] = groups[5]
+
+    # Other info
+    if len(basic) > 8:
+        info = basic[8]
+        idx = info.find("DOF")
+        if idx != -1:
+            flightplan["departure_date"] = info[idx + 4 : idx + 10]
+
+        flightplan["other_info"] = info.strip()
+
+    # Supl. Info
+    if len(basic) > 9:
+        sup_match = re.findall(r"(\D{1}[\/]{1})", basic[9])
+        if sup_match:
+            suplInfo = {}
+            for i in range(len(sup_match) - 1):
+                this_key = sup_match[i]
+                this_idx = basic[9].find(this_key)
+
+                next_key = sup_match[i + 1]
+                next_idx = basic[9].find(next_key)
+
+                val = basic[9][this_idx + 2 : next_idx - 1]
+                suplInfo[this_key[0]] = val
+
+            last_key = sup_match[-1]
+            last_idx = basic[9].find(last_key)
+            suplInfo[last_key[0]] = basic[9][last_idx + 2 :]
+
+            flightplan["supplementary_info"] = suplInfo
+
+    return flightplan

pycontrails/core/fuel.py

@@ -0,0 +1,140 @@
+"""Fuel data support."""
+
+from __future__ import annotations
+
+import dataclasses
+
+import numpy as np
+
+
+@dataclasses.dataclass(frozen=True)
+class Fuel:
+    """Base class for the physical parameters of the fuel."""
+
+    #: Fuel Name
+    fuel_name: str
+
+    #: Lower calorific value (LCV) of fuel, :math:`[J \ kg_{fuel}^{-1}]`
+    q_fuel: float
+
+    #: Percentage of hydrogen mass content in the fuel
+    hydrogen_content: float
+
+    #: CO2 emissions index for fuel, :math:`[kg_{CO_{2}} \ kg_{fuel}^{-1}]`
+    ei_co2: float
+
+    #: Water vapour emissions index for fuel, :math:`[kg_{H_{2}O} \ kg_{fuel}^{-1}]`
+    ei_h2o: float
+
+    #: Sulphur oxide, SO2-S gas, emissions index for fuel, :math:`[kg_{SO_{2}} \ kg_{fuel}^{-1}]`
+    ei_so2: float
+
+    #: Sulphates, S(VI)-S particle, emissions index for fuel, :math:`[kg_{S} \ kg_{fuel}^{-1}]`
+    ei_sulphates: float
+
+    #: Organic carbon emissions index for fuel, :math:`[kg_{OC} \ kg_{fuel}^{-1}]`
+    ei_oc: float
+
+
+@dataclasses.dataclass(frozen=True)
+class JetA(Fuel):
+    """Jet A-1 Fuel.
+
+    References
+    ----------
+    - :cite:`celikel2001forecasting`
+    - :cite:`leeContributionGlobalAviation2021`
+    - :cite:`stettlerAirQualityPublic2011`
+    - :cite:`wilkersonAnalysisEmissionData2010`
+    """
+
+    fuel_name: str = "Jet A-1"
+    q_fuel: float = 43.13e6
+    hydrogen_content: float = 13.8
+    ei_co2: float = 3.159
+    ei_h2o: float = 1.23
+
+    #: Sulphur oxide, SO2-S gas, emissions index for fuel, :math:`[kg_{SO_{2}} \ kg_{fuel}^{-1}]`
+    #: - The EI SO2 is proportional to the fuel sulphur content
+    #: - Celikel (2001): EI_SO2 = 0.84 g/kg-fuel for 450 ppm fuel
+    #: - Lee et al. (2021): EI_SO2 = 1.2 g/kg-fuel for 600 ppm fuel
+    ei_so2: float = 0.0012
+
+    #: Sulphates, S(VI)-S particle, emissions index for fuel, :math:`[kg_{S} \ kg_{fuel}^{-1}]`
+    #: - The SOx-S is partitioned into 98% SO2-S gas and 2% S(VI)-S particle
+    #: - References: Wilkerson et al. (2010) & Stettler et al. (2011)
+    ei_sulphates: float = ei_so2 / 0.98 * 0.02
+
+    #: Organic carbon emissions index for fuel, :math:`[kg_{OC} \ kg_{fuel}^{-1}]`
+    #: - High uncertainty
+    #: - Wilkerson et al. (2010): EI_OC = 15 mg/kg-fuel
+    #: - Stettler et al. (2011): EI_OC = 20 [1, 40] mg/kg-fuel
+    ei_oc: float = 20 * 1e-6
+
+
+class SAFBlend(Fuel):
+    """Jet A-1 / Sustainable Aviation Fuel Blend.
+
+    SAF only changes the CO2 lifecycle emissions, not the CO2 emissions emitted at the
+    aircraft exhaust. We assume that the EI OC stays the same as Jet A-1 fuel due to lack
+    of data.
+
+    Parameters
+    ----------
+    pct_blend : float
+        Sustainable aviation fuel percentage blend ratio by volume, %. Expected
+        to be in the interval ``[0, 100]``.
+
+    References
+    ----------
+    - :cite:`teohTargetedUseSustainable2022`
+    - :cite:`schrippAircraftEngineParticulate2022`
+    """
+
+    def __init__(self, pct_blend: float) -> None:
+        if pct_blend < 0.0 or pct_blend > 100.0:
+            raise ValueError("pct_blend only accepts a value of between 0 and 100.")
+
+        self.pct_blend = pct_blend
+
+        fuel_name = "Jet A-1 / Sustainable Aviation Fuel Blend"
+
+        # We take the default values for Jet-A and modify them for a custom blend
+        base_fuel = JetA()
+        q_fuel = base_fuel.q_fuel + (10700.0 * self.pct_blend)
+        hydrogen_content = base_fuel.hydrogen_content + 0.015 * self.pct_blend
+        ei_co2 = base_fuel.ei_co2
+        ei_h2o = base_fuel.ei_h2o * (hydrogen_content / base_fuel.hydrogen_content)
+        ei_so2 = base_fuel.ei_so2 * (1.0 - self.pct_blend / 100.0)
+        ei_sulphates = ei_so2 / 0.98 * 0.02
+        ei_oc = base_fuel.ei_oc
+
+        super().__init__(
+            fuel_name=fuel_name,
+            q_fuel=q_fuel,
+            hydrogen_content=hydrogen_content,
+            ei_co2=ei_co2,
+            ei_h2o=ei_h2o,
+            ei_so2=ei_so2,
+            ei_sulphates=ei_sulphates,
+            ei_oc=ei_oc,
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class HydrogenFuel(Fuel):
+    """Hydrogen Fuel.
+
+    References
+    ----------
+    - :cite:`khanEmissionsWaterVapour2022`
+    """
+
+    fuel_name: str = "Hydrogen"
+    q_fuel: float = 122.8e6
+    hydrogen_content: float = np.nan
+    ei_co2: float = 0.0
+    ei_h2o: float = 9.21
+    ei_so2: float = 0.0
+    ei_sulphates: float = 0.0
+    ei_oc: float = 0.0