pycontrails 0.54.2__cp312-cp312-macosx_11_0_arm64.whl → 0.54.4__cp312-cp312-macosx_11_0_arm64.whl

pycontrails/__init__.py

@@ -1,7 +1,7 @@
 """
 ``pycontrails`` public API.
 
-Copyright 2021-2023 Breakthrough Energy
+Copyright 2021-present Breakthrough Energy
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -60,8 +60,8 @@ __all__ = [
     "HydrogenFuel",
     "JetA",
     "MetDataArray",
-    "MetDataset",
     "MetDataSource",
+    "MetDataset",
     "MetVariable",
     "Model",
     "ModelParams",

pycontrails/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.54.2'
-__version_tuple__ = version_tuple = (0, 54, 2)
+__version__ = version = '0.54.4'
+__version_tuple__ = version_tuple = (0, 54, 4)

pycontrails/core/__init__.py

@@ -20,8 +20,8 @@ __all__ = [
     "HydrogenFuel",
     "JetA",
     "MetDataArray",
-    "MetDataset",
     "MetDataSource",
+    "MetDataset",
     "MetVariable",
     "Model",
     "ModelParams",

pycontrails/core/aircraft_performance.py

@@ -26,7 +26,9 @@ from pycontrails.physics import jet
 from pycontrails.utils.types import ArrayOrFloat
 
 #: Default load factor for aircraft performance models.
-DEFAULT_LOAD_FACTOR = 0.7
+#: See :func:`pycontrails.physics.jet.aircraft_load_factor`
+#: for a higher precision approach to estimating the load factor.
+DEFAULT_LOAD_FACTOR = 0.83
 
 
 # --------------------------------------
@@ -35,7 +37,19 @@ DEFAULT_LOAD_FACTOR = 0.7
 
 
 @dataclasses.dataclass
-class AircraftPerformanceParams(ModelParams):
+class CommonAircraftPerformanceParams:
+    """Params for :class:`AircraftPerformanceParams` and :class:`AircraftPerformanceGridParams`."""
+
+    #: Account for "in-service" engine deterioration between maintenance cycles.
+    #: Default value is set to +2.5% increase in fuel consumption.
+    #: Reference:
+    #: Gurrola Arrieta, M.D.J., Botez, R.M. and Lasne, A., 2024. An Engine Deterioration Model for
+    #: Predicting Fuel Consumption Impact in a Regional Aircraft. Aerospace, 11(6), p.426.
+    engine_deterioration_factor: float = 0.025
+
+
+@dataclasses.dataclass
+class AircraftPerformanceParams(ModelParams, CommonAircraftPerformanceParams):
     """Parameters for :class:`AircraftPerformance`."""
 
     #: Whether to correct fuel flow to ensure it remains within
@@ -149,14 +163,14 @@ class AircraftPerformance(Model):
         self,
         *,
         aircraft_type: str,
-        altitude_ft: npt.NDArray[np.float64],
+        altitude_ft: npt.NDArray[np.floating],
         time: npt.NDArray[np.datetime64],
-        true_airspeed: npt.NDArray[np.float64],
-        air_temperature: npt.NDArray[np.float64],
-        aircraft_mass: npt.NDArray[np.float64] | float | None,
-        thrust: npt.NDArray[np.float64] | float | None,
-        engine_efficiency: npt.NDArray[np.float64] | float | None,
-        fuel_flow: npt.NDArray[np.float64] | float | None,
+        true_airspeed: npt.NDArray[np.floating],
+        air_temperature: npt.NDArray[np.floating],
+        aircraft_mass: npt.NDArray[np.floating] | float | None,
+        thrust: npt.NDArray[np.floating] | float | None,
+        engine_efficiency: npt.NDArray[np.floating] | float | None,
+        fuel_flow: npt.NDArray[np.floating] | float | None,
         q_fuel: float,
         n_iter: int,
         amass_oew: float,
@@ -178,21 +192,21 @@ class AircraftPerformance(Model):
         ----------
         aircraft_type: str
             Aircraft type designator used to query the underlying model database.
-        altitude_ft: npt.NDArray[np.float64]
+        altitude_ft: npt.NDArray[np.floating]
             Altitude at each waypoint, [:math:`ft`]
         time: npt.NDArray[np.datetime64]
             Waypoint time in ``np.datetime64`` format.
-        true_airspeed: npt.NDArray[np.float64]
+        true_airspeed: npt.NDArray[np.floating]
             True airspeed for each waypoint, [:math:`m s^{-1}`]
-        air_temperature : npt.NDArray[np.float64]
+        air_temperature : npt.NDArray[np.floating]
             Ambient temperature for each waypoint, [:math:`K`]
-        aircraft_mass : npt.NDArray[np.float64] | float | None
+        aircraft_mass : npt.NDArray[np.floating] | float | None
             Override the aircraft_mass at each waypoint, [:math:`kg`].
-        thrust : npt.NDArray[np.float64] | float | None
+        thrust : npt.NDArray[np.floating] | float | None
             Override the thrust setting at each waypoint, [:math: `N`].
-        engine_efficiency : npt.NDArray[np.float64] | float | None
+        engine_efficiency : npt.NDArray[np.floating] | float | None
             Override the engine efficiency at each waypoint.
-        fuel_flow : npt.NDArray[np.float64] | float | None
+        fuel_flow : npt.NDArray[np.floating] | float | None
             Override the fuel flow at each waypoint, [:math:`kg s^{-1}`].
         q_fuel : float
             Lower calorific value (LCV) of fuel, [:math:`J \ kg_{fuel}^{-1}`].
@@ -266,14 +280,14 @@ class AircraftPerformance(Model):
         self,
         *,
         aircraft_type: str,
-        altitude_ft: npt.NDArray[np.float64],
+        altitude_ft: npt.NDArray[np.floating],
         time: npt.NDArray[np.datetime64],
-        true_airspeed: npt.NDArray[np.float64],
-        air_temperature: npt.NDArray[np.float64],
-        aircraft_mass: npt.NDArray[np.float64] | float,
-        thrust: npt.NDArray[np.float64] | float | None,
-        engine_efficiency: npt.NDArray[np.float64] | float | None,
-        fuel_flow: npt.NDArray[np.float64] | float | None,
+        true_airspeed: npt.NDArray[np.floating],
+        air_temperature: npt.NDArray[np.floating],
+        aircraft_mass: npt.NDArray[np.floating] | float,
+        thrust: npt.NDArray[np.floating] | float | None,
+        engine_efficiency: npt.NDArray[np.floating] | float | None,
+        fuel_flow: npt.NDArray[np.floating] | float | None,
         q_fuel: float,
         **kwargs: Any,
     ) -> AircraftPerformanceData:
@@ -318,13 +332,13 @@ class AircraftPerformance(Model):
         self,
         *,
         aircraft_type: str,
-        altitude_ft: npt.NDArray[np.float64],
+        altitude_ft: npt.NDArray[np.floating],
         time: npt.NDArray[np.datetime64],
-        true_airspeed: npt.NDArray[np.float64],
-        air_temperature: npt.NDArray[np.float64],
-        thrust: npt.NDArray[np.float64] | float | None,
-        engine_efficiency: npt.NDArray[np.float64] | float | None,
-        fuel_flow: npt.NDArray[np.float64] | float | None,
+        true_airspeed: npt.NDArray[np.floating],
+        air_temperature: npt.NDArray[np.floating],
+        thrust: npt.NDArray[np.floating] | float | None,
+        engine_efficiency: npt.NDArray[np.floating] | float | None,
+        fuel_flow: npt.NDArray[np.floating] | float | None,
         q_fuel: float,
         n_iter: int,
         amass_oew: float,
@@ -337,7 +351,7 @@ class AircraftPerformance(Model):
         # Variable aircraft_mass will change dynamically after each iteration
         # Set the initial aircraft mass depending on a possible load factor
 
-        aircraft_mass: npt.NDArray[np.float64] | float
+        aircraft_mass: npt.NDArray[np.floating] | float
         if takeoff_mass is not None:
             aircraft_mass = takeoff_mass
         else:
@@ -397,14 +411,14 @@ class AircraftPerformance(Model):
         self,
         *,
         aircraft_type: str,
-        altitude_ft: npt.NDArray[np.float64],
-        air_temperature: npt.NDArray[np.float64],
+        altitude_ft: npt.NDArray[np.floating],
+        air_temperature: npt.NDArray[np.floating],
         time: npt.NDArray[np.datetime64] | None,
-        true_airspeed: npt.NDArray[np.float64] | float | None,
-        aircraft_mass: npt.NDArray[np.float64] | float,
-        engine_efficiency: npt.NDArray[np.float64] | float | None,
-        fuel_flow: npt.NDArray[np.float64] | float | None,
-        thrust: npt.NDArray[np.float64] | float | None,
+        true_airspeed: npt.NDArray[np.floating] | float | None,
+        aircraft_mass: npt.NDArray[np.floating] | float,
+        engine_efficiency: npt.NDArray[np.floating] | float | None,
+        fuel_flow: npt.NDArray[np.floating] | float | None,
+        thrust: npt.NDArray[np.floating] | float | None,
         q_fuel: float,
         **kwargs: Any,
     ) -> AircraftPerformanceData:
@@ -427,24 +441,24 @@ class AircraftPerformance(Model):
         ----------
         aircraft_type : str
             Used to query the underlying model database for aircraft engine parameters.
-        altitude_ft : npt.NDArray[np.float64]
+        altitude_ft : npt.NDArray[np.floating]
             Altitude at each waypoint, [:math:`ft`]
-        air_temperature : npt.NDArray[np.float64]
+        air_temperature : npt.NDArray[np.floating]
             Ambient temperature for each waypoint, [:math:`K`]
         time: npt.NDArray[np.datetime64] | None
             Waypoint time in ``np.datetime64`` format. If None, only drag force
             will is used in thrust calculations (ie, no vertical change and constant
             horizontal change). In addition, aircraft is assumed to be in cruise.
-        true_airspeed : npt.NDArray[np.float64] | float | None
+        true_airspeed : npt.NDArray[np.floating] | float | None
             True airspeed for each waypoint, [:math:`m s^{-1}`].
             If None, a nominal value is used.
-        aircraft_mass : npt.NDArray[np.float64] | float
+        aircraft_mass : npt.NDArray[np.floating] | float
             Aircraft mass for each waypoint, [:math:`kg`].
-        engine_efficiency : npt.NDArray[np.float64] | float | None
+        engine_efficiency : npt.NDArray[np.floating] | float | None
             Override the engine efficiency at each waypoint.
-        fuel_flow : npt.NDArray[np.float64] | float | None
+        fuel_flow : npt.NDArray[np.floating] | float | None
             Override the fuel flow at each waypoint, [:math:`kg s^{-1}`].
-        thrust : npt.NDArray[np.float64] | float | None
+        thrust : npt.NDArray[np.floating] | float | None
             Override the thrust setting at each waypoint, [:math: `N`].
         q_fuel : float
             Lower calorific value (LCV) of fuel, [:math:`J \ kg_{fuel}^{-1}`].
@@ -457,12 +471,12 @@ class AircraftPerformance(Model):
             Derived performance metrics at each waypoint.
         """
 
-    def ensure_true_airspeed_on_source(self) -> npt.NDArray[np.float64]:
+    def ensure_true_airspeed_on_source(self) -> npt.NDArray[np.floating]:
         """Add ``true_airspeed`` field to :attr:`source` data if not already present.
 
         Returns
         -------
-        npt.NDArray[np.float64]
+        npt.NDArray[np.floating]
             True airspeed, [:math:`m s^{-1}`]. If ``true_airspeed`` is already present
             on :attr:`source`, this is returned directly. Otherwise, it is calculated
             using :meth:`Flight.segment_true_airspeed`.
@@ -515,30 +529,30 @@ class AircraftPerformanceData:
 
     Parameters
     ----------
-    fuel_flow : npt.NDArray[np.float64]
+    fuel_flow : npt.NDArray[np.floating]
         Fuel mass flow rate for each waypoint, [:math:`kg s^{-1}`]
-    aircraft_mass : npt.NDArray[np.float64]
+    aircraft_mass : npt.NDArray[np.floating]
         Aircraft mass for each waypoint, [:math:`kg`]
-    true_airspeed : npt.NDArray[np.float64]
+    true_airspeed : npt.NDArray[np.floating]
         True airspeed at each waypoint, [:math: `m s^{-1}`]
-    fuel_burn: npt.NDArray[np.float64]
+    fuel_burn: npt.NDArray[np.floating]
         Fuel consumption for each waypoint, [:math:`kg`]. Set to an array of
         all nan values if it cannot be computed (ie, working with gridpoints).
-    thrust: npt.NDArray[np.float64]
+    thrust: npt.NDArray[np.floating]
         Thrust force, [:math:`N`]
-    engine_efficiency: npt.NDArray[np.float64]
+    engine_efficiency: npt.NDArray[np.floating]
         Overall propulsion efficiency for each waypoint
-    rocd : npt.NDArray[np.float64]
+    rocd : npt.NDArray[np.floating]
         Rate of climb and descent, [:math:`ft min^{-1}`]
     """
 
-    fuel_flow: npt.NDArray[np.float64]
-    aircraft_mass: npt.NDArray[np.float64]
-    true_airspeed: npt.NDArray[np.float64]
-    fuel_burn: npt.NDArray[np.float64]
-    thrust: npt.NDArray[np.float64]
-    engine_efficiency: npt.NDArray[np.float64]
-    rocd: npt.NDArray[np.float64]
+    fuel_flow: npt.NDArray[np.floating]
+    aircraft_mass: npt.NDArray[np.floating]
+    true_airspeed: npt.NDArray[np.floating]
+    fuel_burn: npt.NDArray[np.floating]
+    thrust: npt.NDArray[np.floating]
+    engine_efficiency: npt.NDArray[np.floating]
+    rocd: npt.NDArray[np.floating]
 
 
 # --------------------------------
@@ -547,7 +561,7 @@ class AircraftPerformanceData:
 
 
 @dataclasses.dataclass
-class AircraftPerformanceGridParams(ModelParams):
+class AircraftPerformanceGridParams(ModelParams, CommonAircraftPerformanceParams):
     """Parameters for :class:`AircraftPerformanceGrid`."""
 
     #: Fuel type

pycontrails/core/cache.py

@@ -43,7 +43,7 @@ def _get_user_cache_dir() -> str:
 class CacheStore(ABC):
     """Abstract cache storage class for storing staged and intermediate data."""
 
-    __slots__ = ("cache_dir", "allow_clear")
+    __slots__ = ("allow_clear", "cache_dir")
     cache_dir: str
     allow_clear: bool
 
@@ -426,15 +426,15 @@ class GCPCacheStore(CacheStore):
     """
 
     __slots__ = (
-        "project",
+        "_bucket",
+        "_client",
+        "_disk_cache",
         "bucket",
+        "chunk_size",
+        "project",
         "read_only",
-        "timeout",
         "show_progress",
-        "chunk_size",
-        "_disk_cache",
-        "_client",
-        "_bucket",
+        "timeout",
     )
     project: str | None
     bucket: str

pycontrails/core/fleet.py

@@ -32,7 +32,7 @@ class Fleet(Flight):
     Flight waypoints are merged into a single :class:`Flight`-like object.
     """
 
-    __slots__ = ("fl_attrs", "final_waypoints")
+    __slots__ = ("final_waypoints", "fl_attrs")
 
     def __init__(
         self,
@@ -132,13 +132,13 @@ class Fleet(Flight):
         return final_waypoints, fl_attrs
 
     @override
-    def copy(self, **kwargs: Any) -> Fleet:
+    def copy(self, **kwargs: Any) -> Self:
         kwargs.setdefault("fuel", self.fuel)
         kwargs.setdefault("fl_attrs", self.fl_attrs)
         return super().copy(**kwargs)
 
     @override
-    def filter(self, mask: npt.NDArray[np.bool_], copy: bool = True, **kwargs: Any) -> Fleet:
+    def filter(self, mask: npt.NDArray[np.bool_], copy: bool = True, **kwargs: Any) -> Self:
         kwargs.setdefault("fuel", self.fuel)
 
         flight_ids = set(np.unique(self["flight_id"][mask]))
@@ -162,7 +162,6 @@ class Fleet(Flight):
         cls,
         seq: Iterable[Flight],
         broadcast_numeric: bool = True,
-        copy: bool = True,
         attrs: dict[str, Any] | None = None,
     ) -> Self:
         """Instantiate a :class:`Fleet` instance from an iterable of :class:`Flight`.
@@ -177,8 +176,6 @@ class Fleet(Flight):
             An iterable of :class:`Flight` instances.
         broadcast_numeric : bool, optional
             If True, broadcast numeric attributes to data variables.
-        copy : bool, optional
-            If True, make copy of each flight instance in ``seq``.
         attrs : dict[str, Any] | None, optional
             Global attribute to attach to instance.
 
@@ -190,15 +187,15 @@ class Fleet(Flight):
             in ``seq``.
         """
 
-        def _maybe_copy(fl: Flight) -> Flight:
-            return fl.copy() if copy else fl
+        def _shallow_copy(fl: Flight) -> Flight:
+            return Flight(VectorDataDict(fl.data), attrs=fl.attrs, copy=False, fuel=fl.fuel)
 
         def _maybe_warn(fl: Flight) -> Flight:
             if not fl:
                 warnings.warn("Empty flight found in sequence. It will be filtered out.")
             return fl
 
-        seq = tuple(_maybe_copy(fl) for fl in seq if _maybe_warn(fl))
+        seq = tuple(_shallow_copy(fl) for fl in seq if _maybe_warn(fl))
 
         if not seq:
             msg = "Cannot create Fleet from empty sequence."
@@ -265,12 +262,12 @@ class Fleet(Flight):
 
     def segment_true_airspeed(
         self,
-        u_wind: npt.NDArray[np.float64] | float = 0.0,
-        v_wind: npt.NDArray[np.float64] | float = 0.0,
+        u_wind: npt.NDArray[np.floating] | float = 0.0,
+        v_wind: npt.NDArray[np.floating] | float = 0.0,
         smooth: bool = True,
         window_length: int = 7,
         polyorder: int = 1,
-    ) -> npt.NDArray[np.float64]:
+    ) -> npt.NDArray[np.floating]:
         """Calculate the true airspeed [:math:`m / s`] from the ground speed and horizontal winds.
 
         Because Flight.segment_true_airspeed uses a smoothing pattern, waypoints in :attr:`data`
@@ -302,7 +299,7 @@ class Fleet(Flight):
             self[key] = v_wind
 
         # Calculate TAS on each flight individually
-        def calc_tas(fl: Flight) -> npt.NDArray[np.float64]:
+        def calc_tas(fl: Flight) -> npt.NDArray[np.floating]:
             u = fl.get("__u_wind", u_wind)
             v = fl.get("__v_wind", v_wind)
 
@@ -325,19 +322,27 @@ class Fleet(Flight):
         return np.concatenate(tas)
 
     @override
-    def segment_groundspeed(self, *args: Any, **kwargs: Any) -> npt.NDArray[np.float64]:
+    def segment_groundspeed(self, *args: Any, **kwargs: Any) -> npt.NDArray[np.floating]:
         fls = self.to_flight_list(copy=False)
         gs = [fl.segment_groundspeed(*args, **kwargs) for fl in fls]
         return np.concatenate(gs)
 
     @override
-    def resample_and_fill(self, *args: Any, **kwargs: Any) -> Fleet:
+    def resample_and_fill(self, *args: Any, **kwargs: Any) -> Self:
         flights = self.to_flight_list(copy=False)
+
+        # We need to ensure that each flight has an flight_id attrs field
+        # When we call fl.resample_and_fill, any flight_id data field
+        # will be lost, so the call to Fleet.from_seq will fail.
+        for fl in flights:
+            if "flight_id" not in fl.attrs:
+                fl.attrs["flight_id"] = _extract_flight_id(fl)
+
         flights = [fl.resample_and_fill(*args, **kwargs) for fl in flights]
-        return type(self).from_seq(flights, copy=False, broadcast_numeric=False, attrs=self.attrs)
+        return type(self).from_seq(flights, broadcast_numeric=False, attrs=self.attrs)
 
     @override
-    def segment_length(self) -> npt.NDArray[np.float64]:
+    def segment_length(self) -> npt.NDArray[np.floating]:
         return np.where(self.final_waypoints, np.nan, super().segment_length())
 
     @property
@@ -346,11 +351,11 @@ class Fleet(Flight):
         return np.nanmax(self.segment_length()).item()
 
     @override
-    def segment_azimuth(self) -> npt.NDArray[np.float64]:
+    def segment_azimuth(self) -> npt.NDArray[np.floating]:
         return np.where(self.final_waypoints, np.nan, super().segment_azimuth())
 
     @override
-    def segment_angle(self) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
+    def segment_angle(self) -> tuple[npt.NDArray[np.floating], npt.NDArray[np.floating]]:
         sin_a, cos_a = super().segment_angle()
         sin_a[self.final_waypoints] = np.nan
         cos_a[self.final_waypoints] = np.nan
@@ -368,8 +373,7 @@ class Fleet(Flight):
         force_filter: bool = False,
         drop: bool = True,
         keep_original_index: bool = False,
-        climb_descend_at_end: bool = False,
-    ) -> Flight:
+    ) -> NoReturn:
         msg = "Only implemented for Flight instances"
         raise NotImplementedError(msg)