pycontrails 0.54.1__cp313-cp313-macosx_11_0_arm64.whl → 0.54.3__cp313-cp313-macosx_11_0_arm64.whl

pycontrails/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.54.1'
-__version_tuple__ = version_tuple = (0, 54, 1)
+__version__ = version = '0.54.3'
+__version_tuple__ = version_tuple = (0, 54, 3)

pycontrails/core/aircraft_performance.py

@@ -4,12 +4,17 @@ from __future__ import annotations
 
 import abc
 import dataclasses
+import sys
 import warnings
 from typing import Any, Generic, NoReturn, overload
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 import numpy as np
 import numpy.typing as npt
-from overrides import overrides
 
 from pycontrails.core import flight, fuel
 from pycontrails.core.fleet import Fleet
@@ -21,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
 
 
 # --------------------------------------
@@ -30,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
@@ -123,7 +142,7 @@ class AircraftPerformance(Model):
             Flight trajectory with aircraft performance data.
         """
 
-    @overrides
+    @override
     def set_source_met(self, *args: Any, **kwargs: Any) -> None:
         fill_with_isa = self.params["fill_low_altitude_with_isa_temperature"]
         if fill_with_isa and (self.met is None or "air_temperature" not in self.met):
@@ -542,7 +561,7 @@ class AircraftPerformanceData:
 
 
 @dataclasses.dataclass
-class AircraftPerformanceGridParams(ModelParams):
+class AircraftPerformanceGridParams(ModelParams, CommonAircraftPerformanceParams):
     """Parameters for :class:`AircraftPerformanceGrid`."""
 
     #: Fuel type

pycontrails/core/cache.py

@@ -7,14 +7,18 @@ import logging
 import os
 import pathlib
 import shutil
+import sys
 import warnings
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any
 
-logger = logging.getLogger(__name__)
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
 
-from overrides import overrides
+logger = logging.getLogger(__name__)
 
 from pycontrails.utils import dependencies
 
@@ -203,20 +207,20 @@ class DiskCacheStore(CacheStore):
         return f"DiskCacheStore: {self.cache_dir}"
 
     @property
-    @overrides
+    @override
     def size(self) -> float:
         disk_path = pathlib.Path(self.cache_dir)
         size = sum(f.stat().st_size for f in disk_path.rglob("*") if f.is_file())
         logger.debug("Disk cache size %s bytes", size)
         return size / 1e6
 
-    @overrides
+    @override
     def listdir(self, path: str = "") -> list[str]:
         path = self.path(path)
         iter_ = pathlib.Path(path).iterdir()
         return sorted(str(f.relative_to(path)) for f in iter_)
 
-    @overrides
+    @override
     def path(self, cache_path: str) -> str:
         if cache_path.startswith(self.cache_dir):
             disk_path = pathlib.Path(cache_path)
@@ -228,7 +232,7 @@ class DiskCacheStore(CacheStore):
 
         return str(disk_path)
 
-    @overrides
+    @override
     def exists(self, cache_path: str) -> bool:
         disk_path = pathlib.Path(self.path(cache_path))
         return disk_path.exists()
@@ -551,7 +555,7 @@ class GCPCacheStore(CacheStore):
         return self._client
 
     @property
-    @overrides
+    @override
     def size(self) -> float:
         # get list of blobs below this path
         blobs = self._bucket.list_blobs(prefix=self.cache_dir)
@@ -559,7 +563,7 @@ class GCPCacheStore(CacheStore):
         logger.debug("GCP cache size %s bytes", size)
         return size / 1e6
 
-    @overrides
+    @override
     def listdir(self, path: str = "") -> list[str]:
         # I don't necessarily think we want to implement this .... it might be
         # very slow if the bucket is large. BUT, it won't be slower than the size
@@ -572,7 +576,7 @@ class GCPCacheStore(CacheStore):
             "list files in the local disk cache."
         )
 
-    @overrides
+    @override
     def path(self, cache_path: str) -> str:
         if cache_path.startswith(self.cache_dir):
             return cache_path
@@ -604,7 +608,7 @@ class GCPCacheStore(CacheStore):
         bucket_path = self.path(cache_path)
         return f"gs://{self.bucket}/{bucket_path}"
 
-    @overrides
+    @override
     def exists(self, cache_path: str) -> bool:
         # see if file is in the mirror disk cache
         if self._disk_cache.exists(cache_path):

pycontrails/core/fleet.py

@@ -2,14 +2,24 @@
 
 from __future__ import annotations
 
+import sys
 import warnings
 from collections.abc import Iterable
 from typing import Any, NoReturn
 
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
-from overrides import overrides
 
 from pycontrails.core.flight import Flight
 from pycontrails.core.fuel import Fuel, JetA
@@ -121,13 +131,13 @@ class Fleet(Flight):
 
         return final_waypoints, fl_attrs
 
-    @overrides
+    @override
     def copy(self, **kwargs: Any) -> Fleet:
         kwargs.setdefault("fuel", self.fuel)
         kwargs.setdefault("fl_attrs", self.fl_attrs)
         return super().copy(**kwargs)
 
-    @overrides
+    @override
     def filter(self, mask: npt.NDArray[np.bool_], copy: bool = True, **kwargs: Any) -> Fleet:
         kwargs.setdefault("fuel", self.fuel)
 
@@ -137,7 +147,7 @@ class Fleet(Flight):
 
         return super().filter(mask, copy=copy, **kwargs)
 
-    @overrides
+    @override
     def sort(self, by: str | list[str]) -> NoReturn:
         msg = (
             "Fleet.sort is not implemented. A Fleet instance must be sorted "
@@ -154,7 +164,7 @@ class Fleet(Flight):
         broadcast_numeric: bool = True,
         copy: bool = True,
         attrs: dict[str, Any] | None = None,
-    ) -> Fleet:
+    ) -> Self:
         """Instantiate a :class:`Fleet` instance from an iterable of :class:`Flight`.
 
         .. versionchanged:: 0.49.3
@@ -314,39 +324,39 @@ class Fleet(Flight):
         # use case isn't seen.
         return np.concatenate(tas)
 
-    @overrides
+    @override
     def segment_groundspeed(self, *args: Any, **kwargs: Any) -> npt.NDArray[np.float64]:
         fls = self.to_flight_list(copy=False)
         gs = [fl.segment_groundspeed(*args, **kwargs) for fl in fls]
         return np.concatenate(gs)
 
-    @overrides
+    @override
     def resample_and_fill(self, *args: Any, **kwargs: Any) -> Fleet:
         flights = self.to_flight_list(copy=False)
         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)
 
-    @overrides
+    @override
     def segment_length(self) -> npt.NDArray[np.float64]:
         return np.where(self.final_waypoints, np.nan, super().segment_length())
 
     @property
-    @overrides
+    @override
     def max_distance_gap(self) -> float:
         return np.nanmax(self.segment_length()).item()
 
-    @overrides
+    @override
     def segment_azimuth(self) -> npt.NDArray[np.float64]:
         return np.where(self.final_waypoints, np.nan, super().segment_azimuth())
 
-    @overrides
+    @override
     def segment_angle(self) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
         sin_a, cos_a = super().segment_angle()
         sin_a[self.final_waypoints] = np.nan
         cos_a[self.final_waypoints] = np.nan
         return sin_a, cos_a
 
-    @overrides
+    @override
     def clean_and_resample(
         self,
         freq: str = "1min",

pycontrails/core/flight.py

@@ -4,14 +4,20 @@ from __future__ import annotations
 
 import enum
 import logging
+import sys
 import warnings
 from typing import TYPE_CHECKING, Any, NoReturn, TypeVar
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
 import scipy.signal
-from overrides import overrides
 
 from pycontrails.core.fuel import Fuel, JetA
 from pycontrails.core.vector import AttrDict, GeoVectorDataset, VectorDataDict, VectorDataset
@@ -115,6 +121,8 @@ class Flight(GeoVectorDataset):
           calculations with the ICAO Aircraft Emissions Databank (EDB).
         - ``max_mach_number``: Maximum Mach number at cruise altitude. Used by
           some aircraft performance models to clip true airspeed.
+        - ``load_factor``: The load factor used in determining the aircraft's
+          take-off weight. Used by some aircraft performance models.
 
         Numeric quantities that are constant over the entire flight trajectory
         should be included as attributes.
@@ -276,19 +284,19 @@ class Flight(GeoVectorDataset):
                     "'drop_duplicated_times=True' or call the 'resample_and_fill' method."
                 )
 
-    @overrides
+    @override
     def copy(self: FlightType, **kwargs: Any) -> FlightType:
         kwargs.setdefault("fuel", self.fuel)
         return super().copy(**kwargs)
 
-    @overrides
+    @override
     def filter(
         self: FlightType, mask: npt.NDArray[np.bool_], copy: bool = True, **kwargs: Any
     ) -> FlightType:
         kwargs.setdefault("fuel", self.fuel)
         return super().filter(mask, copy=copy, **kwargs)
 
-    @overrides
+    @override
     def sort(self, by: str | list[str]) -> NoReturn:
         msg = (
             "Flight.sort is not implemented. A Flight instance is automatically sorted "
@@ -955,7 +963,7 @@ class Flight(GeoVectorDataset):
                 msg = f"{msg} Pass 'keep_original_index=True' to keep the original index."
             warnings.warn(msg)
 
-        return Flight(data=df, attrs=self.attrs)
+        return Flight(data=df, attrs=self.attrs, fuel=self.fuel)
 
     def clean_and_resample(
         self,
@@ -1091,7 +1099,7 @@ class Flight(GeoVectorDataset):
 
         Notes
         -----
-        Algorithm is derived from :meth:`traffic.core.flight.Flight.filter`.
+        Algorithm is derived from :meth:`traffic.core.Flight.filter`.
 
         The `traffic
         <https://traffic-viz.github.io/api_reference/traffic.core.flight.html#traffic.core.Flight.filter>`_
@@ -1419,19 +1427,21 @@ class Flight(GeoVectorDataset):
         return {"type": "FeatureCollection", "features": features}
 
     def to_traffic(self) -> traffic.core.Flight:
-        """Convert Flight instance to :class:`traffic.core.Flight` instance.
-
-        See https://traffic-viz.github.io/traffic.core.flight.html#traffic.core.Flight
+        """Convert to :class:`traffic.core.Flight`instance.
 
         Returns
         -------
-        :class:`traffic.core.Flight`
-            `traffic.core.Flight` instance
+        traffic.core.Flight
+            traffic flight instance
 
         Raises
         ------
         ModuleNotFoundError
             `traffic` package not installed
+
+        See Also
+        --------
+        :class:`traffic.core.Flight`
         """
         try:
             import traffic.core
@@ -1977,18 +1987,18 @@ def filter_altitude(
 
     Notes
     -----
-    Algorithm is derived from :meth:`traffic.core.flight.Flight.filter`.
+    Algorithm is derived from :meth:`traffic.core.Flight.filter`.
 
-    The `traffic
+    The `traffic filter algorithm
     <https://traffic-viz.github.io/api_reference/traffic.core.flight.html#traffic.core.Flight.filter>`_
-    algorithm also computes thresholds on sliding windows
+    also computes thresholds on sliding windows
     and replaces unacceptable values with NaNs.
 
     Errors may raised if the ``kernel_size`` is too large.
 
     See Also
     --------
-    :meth:`traffic.core.flight.Flight.filter`
+    :meth:`traffic.core.Flight.filter`
     :func:`scipy.signal.medfilt`
     """
     if not len(altitude_ft):

pycontrails/core/met.py

@@ -6,6 +6,7 @@ import hashlib
 import json
 import logging
 import pathlib
+import sys
 import typing
 import warnings
 from abc import ABC, abstractmethod
@@ -29,11 +30,20 @@ from typing import (
     overload,
 )
 
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
 import xarray as xr
-from overrides import overrides
 
 from pycontrails.core import interpolation
 from pycontrails.core import vector as vector_module
@@ -863,13 +873,13 @@ class MetDataset(MetBase):
         return key in self.data
 
     @property
-    @overrides
+    @override
     def shape(self) -> tuple[int, int, int, int]:
         sizes = self.data.sizes
         return sizes["longitude"], sizes["latitude"], sizes["level"], sizes["time"]
 
     @property
-    @overrides
+    @override
     def size(self) -> int:
         return np.prod(self.shape).item()
 
@@ -978,7 +988,7 @@ class MetDataset(MetBase):
         hash: str,
         cachestore: CacheStore | None = None,
         chunks: dict[str, int] | None = None,
-    ) -> MetDataset:
+    ) -> Self:
         """Load saved intermediate from :attr:`cachestore`.
 
         Parameters
@@ -993,7 +1003,7 @@ class MetDataset(MetBase):
 
         Returns
         -------
-        MetDataset
+        Self
             New MetDataArray with loaded data.
         """
         cachestore = cachestore or DiskCacheStore()
@@ -1015,14 +1025,14 @@ class MetDataset(MetBase):
             cachestore=self.cachestore,
         )
 
-    @overrides
+    @override
     def broadcast_coords(self, name: str) -> xr.DataArray:
         da = xr.ones_like(self.data[next(iter(self.data.keys()))]) * self.data[name]
         da.name = name
 
         return da
 
-    @overrides
+    @override
     def downselect(self, bbox: tuple[float, ...]) -> MetDataset:
         data = downselect(self.data, bbox)
         return MetDataset(data, cachestore=self.cachestore, copy=False)
@@ -1179,7 +1189,7 @@ class MetDataset(MetBase):
         latitude: npt.ArrayLike | float,
         level: npt.ArrayLike | float,
         time: npt.ArrayLike | np.datetime64,
-    ) -> MetDataset:
+    ) -> Self:
         r"""Create a :class:`MetDataset` containing a coordinate skeleton from coordinate arrays.
 
         Parameters
@@ -1193,7 +1203,7 @@ class MetDataset(MetBase):
 
         Returns
         -------
-        MetDataset
+        Self
             MetDataset with no variables.
 
         Examples
@@ -1279,7 +1289,7 @@ class MetDataset(MetBase):
         return cls(xr.Dataset({}, coords=coords))
 
     @classmethod
-    def from_zarr(cls, store: Any, **kwargs: Any) -> MetDataset:
+    def from_zarr(cls, store: Any, **kwargs: Any) -> Self:
         """Create a :class:`MetDataset` from a path to a Zarr store.
 
         Parameters
@@ -1291,7 +1301,7 @@ class MetDataset(MetBase):
 
         Returns
         -------
-        MetDataset
+        Self
             MetDataset with data from Zarr store.
         """
         kwargs.setdefault("storage_options", {"read_only": True})
@@ -1400,8 +1410,9 @@ class MetDataArray(MetBase):
 
         See Also
         --------
-        - :meth:`xr.Dataset.load`
-        - :meth:`xr.DataArray.load`
+        :meth:`xarray.Dataset.load`
+        :meth:`xarray.DataArray.load`
+
         """
         if not self.in_memory:
             self._check_memory("Extracting numpy array from")
@@ -1432,12 +1443,12 @@ class MetDataArray(MetBase):
         return np.array_equal(self.data, self.data.astype(bool))
 
     @property
-    @overrides
+    @override
     def size(self) -> int:
         return self.data.size
 
     @property
-    @overrides
+    @override
     def shape(self) -> tuple[int, int, int, int]:
         # https://github.com/python/mypy/issues/1178
         return typing.cast(tuple[int, int, int, int], self.data.shape)
@@ -1827,7 +1838,7 @@ class MetDataArray(MetBase):
         hash: str,
         cachestore: CacheStore | None = None,
         chunks: dict[str, int] | None = None,
-    ) -> MetDataArray:
+    ) -> Self:
         """Load saved intermediate from :attr:`cachestore`.
 
         Parameters
@@ -2016,7 +2027,7 @@ class MetDataArray(MetBase):
         See Also
         --------
         :meth:`to_polyhedra`
-        :func:`pycontrails.core.polygons.find_multipolygons`
+        :func:`polygons.find_multipolygons`
 
         Examples
         --------
@@ -2220,7 +2231,7 @@ class MetDataArray(MetBase):
 
         Returns
         -------
-        dict | :class:`o3d.geometry.TriangleMesh`
+        dict | open3d.geometry.TriangleMesh
             Python representation of geojson object or `Open3D Triangle Mesh
             <http://www.open3d.org/docs/release/tutorial/geometry/mesh.html>`_ depending on the
             `return_type` parameter.
@@ -2234,8 +2245,9 @@ class MetDataArray(MetBase):
 
         See Also
         --------
-        :meth:`to_polygons`
-        `skimage.measure.marching_cubes <https://scikit-image.org/docs/dev/api/skimage.measure.html#skimage.measure.marching_cubes>`_
+        :meth:`to_polygon_feature`
+        :func:`skimage.measure.marching_cubes`
+        :class:`open3d.geometry.TriangleMesh`
 
         Notes
         -----
@@ -2380,14 +2392,14 @@ class MetDataArray(MetBase):
             )
         return mesh
 
-    @overrides
+    @override
     def broadcast_coords(self, name: str) -> xr.DataArray:
         da = xr.ones_like(self.data) * self.data[name]
         da.name = name
 
         return da
 
-    @overrides
+    @override
     def downselect(self, bbox: tuple[float, ...]) -> MetDataArray:
         data = downselect(self.data, bbox)
         return MetDataArray(data, cachestore=self.cachestore)