pycontrails 0.52.1__cp312-cp312-win_amd64.whl → 0.52.3__cp312-cp312-win_amd64.whl

pycontrails/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.52.1'
-__version_tuple__ = version_tuple = (0, 52, 1)
+__version__ = version = '0.52.3'
+__version_tuple__ = version_tuple = (0, 52, 3)

pycontrails/core/aircraft_performance.py

@@ -9,6 +9,7 @@ from typing import Any, Generic, NoReturn, overload
 
 import numpy as np
 import numpy.typing as npt
+from overrides import overrides
 
 from pycontrails.core import flight, fuel
 from pycontrails.core.flight import Flight
@@ -39,6 +40,19 @@ class AircraftPerformanceParams(ModelParams):
     #: The default value of 3 is sufficient for most cases.
     n_iter: int = 3
 
+    #: Experimental. If True, fill waypoints below the lowest altitude met
+    #: level with ISA temperature when interpolating "air_temperature" or "t".
+    #: If the ``met`` data is not provided, the entire air temperature array
+    #: is approximated with the ISA temperature. Enabling this does NOT
+    #: remove any NaN values in the ``met`` data itself.
+    fill_low_altitude_with_isa_temperature: bool = False
+
+    #: Experimental. If True, fill waypoints below the lowest altitude met
+    #: level with zero wind when computing true airspeed. In other words,
+    #: approximate low-altitude true airspeed with the ground speed. Enabling
+    #: this does NOT remove any NaN values in the ``met`` data itself.
+    fill_low_altitude_with_zero_wind: bool = False
+
 
 class AircraftPerformance(Model):
     """
@@ -104,6 +118,23 @@ class AircraftPerformance(Model):
             Flight trajectory with aircraft performance data.
         """
 
+    @overrides
+    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):
+            if "air_temperature" in self.source:
+                _fill_low_altitude_with_isa_temperature(self.source, 0.0)
+            else:
+                self.source["air_temperature"] = self.source.T_isa()
+            fill_with_isa = False  # we've just filled it
+
+        super().set_source_met(*args, **kwargs)
+        if not fill_with_isa:
+            return
+
+        met_level_0 = self.met.data["level"][-1].item()  # type: ignore[union-attr]
+        _fill_low_altitude_with_isa_temperature(self.source, met_level_0)
+
     def simulate_fuel_and_performance(
         self,
         *,
@@ -426,27 +457,41 @@ class AircraftPerformance(Model):
             on :attr:`source`, this is returned directly. Otherwise, it is calculated
             using :meth:`Flight.segment_true_airspeed`.
         """
+        tas = self.source.get("true_airspeed")
+        fill_with_groundspeed = self.params["fill_low_altitude_with_zero_wind"]
+
+        if tas is not None:
+            if not fill_with_groundspeed:
+                return tas
+            cond = np.isnan(tas)
+            tas[cond] = self.source.segment_groundspeed()[cond]
+            return tas
+
+        met_incomplete = (
+            self.met is None or "eastward_wind" not in self.met or "northward_wind" not in self.met
+        )
+        if met_incomplete:
+            if fill_with_groundspeed:
+                tas = self.source.segment_groundspeed()
+                self.source["true_airspeed"] = tas
+                return tas
+            msg = (
+                "Cannot compute 'true_airspeed' without 'eastward_wind' and 'northward_wind' "
+                "met data. Either include met data in the model constructor, define "
+                "'true_airspeed' data on the flight, or set "
+                "'fill_low_altitude_with_zero_wind' to True."
+            )
+            raise ValueError(msg)
 
-        try:
-            return self.source["true_airspeed"]
-        except KeyError:
-            pass
-
-        if not isinstance(self.source, Flight):
-            raise TypeError("Model source must be a Flight to calculate true airspeed.")
-
-        # Two step fallback: try to find u_wind and v_wind.
-        try:
-            u = interpolate_met(self.met, self.source, "eastward_wind", **self.interp_kwargs)
-            v = interpolate_met(self.met, self.source, "northward_wind", **self.interp_kwargs)
+        u = interpolate_met(self.met, self.source, "eastward_wind", **self.interp_kwargs)
+        v = interpolate_met(self.met, self.source, "northward_wind", **self.interp_kwargs)
 
-        except (ValueError, KeyError) as exc:
-            raise ValueError(
-                "Variable 'true_airspeed' not found. Include 'eastward_wind' and"
-                " 'northward_wind' variables on 'met' in model constructor, or define"
-                " 'true_airspeed' data on flight. This can be achieved by calling the"
-                " 'Flight.segment_true_airspeed' method."
-            ) from exc
+        if fill_with_groundspeed:
+            met_level_max = self.met.data["level"][-1].item()  # type: ignore[union-attr]
+            cond = self.source.level > met_level_max
+            # We DON'T overwrite the original u and v arrays already attached to the source
+            u = np.where(cond, 0.0, u)
+            v = np.where(cond, 0.0, v)
 
         out = self.source.segment_true_airspeed(u, v)
         self.source["true_airspeed"] = out
@@ -543,3 +588,54 @@ class AircraftPerformanceGridData(Generic[ArrayOrFloat]):
 
     #: Engine efficiency, [:math:`0-1`]
     engine_efficiency: ArrayOrFloat
+
+
+def _fill_low_altitude_with_isa_temperature(vector: GeoVectorDataset, met_level_max: float) -> None:
+    """Fill low-altitude NaN values in ``air_temperature`` with ISA values.
+
+    The ``air_temperature`` param is assumed to have been computed by
+    interpolating against a gridded air temperature field that did not
+    necessarily extend to the surface. This function fills points below the
+    lowest altitude in the gridded data with ISA temperature values.
+
+    This function operates in-place and modifies the ``air_temperature`` field.
+
+    Parameters
+    ----------
+    vector : GeoVectorDataset
+        GeoVectorDataset instance associated with the ``air_temperature`` data.
+    met_level_max : float
+        The maximum level in the met data, [:math:`hPa`].
+    """
+    air_temperature = vector["air_temperature"]
+    is_nan = np.isnan(air_temperature)
+    low_alt = vector.level > met_level_max
+    cond = is_nan & low_alt
+
+    t_isa = vector.T_isa()
+    air_temperature[cond] = t_isa[cond]
+
+
+def _fill_low_altitude_tas_with_true_groundspeed(fl: Flight, met_level_max: float) -> None:
+    """Fill low-altitude NaN values in ``true_airspeed`` with ground speed.
+
+    The ``true_airspeed`` param is assumed to have been computed by
+    interpolating against a gridded wind field that did not necessarily
+    extend to the surface. This function fills points below the lowest
+    altitude in the gridded data with ground speed values.
+
+    This function operates in-place and modifies the ``true_airspeed`` field.
+
+    Parameters
+    ----------
+    fl : Flight
+        Flight instance associated with the ``true_airspeed`` data.
+    met_level_max : float
+        The maximum level in the met data, [:math:`hPa`].
+    """
+    tas = fl["true_airspeed"]
+    is_nan = np.isnan(tas)
+    low_alt = fl.level > met_level_max
+    cond = is_nan & low_alt
+
+    tas[cond] = fl.segment_groundspeed()[cond]

pycontrails/core/fleet.py

@@ -226,28 +226,29 @@ class Fleet(Flight):
         return len(self.fl_attrs)
 
     def to_flight_list(self, copy: bool = True) -> list[Flight]:
-        """De-concatenate merged waypoints into a list of Flight instances.
+        """De-concatenate merged waypoints into a list of :class:`Flight` instances.
 
         Any global :attr:`attrs` are lost.
 
         Parameters
         ----------
         copy : bool, optional
-            If True, make copy of each flight instance in `seq`.
+            If True, make copy of each :class:`Flight` instance.
 
         Returns
         -------
         list[Flight]
-            List of Flights in the same order as was passed into the `Fleet` instance.
+            List of Flights in the same order as was passed into the ``Fleet`` instance.
         """
-
-        # Avoid self.dataframe to purposely drop global attrs
-        tmp = pd.DataFrame(self.data, copy=copy)
-        grouped = tmp.groupby("flight_id", sort=False)
-
+        indices = self.dataframe.groupby("flight_id", sort=False).indices
         return [
-            Flight(df, attrs=self.fl_attrs[flight_id], fuel=self.fuel, copy=copy)
-            for flight_id, df in grouped
+            Flight(
+                data=VectorDataDict({k: v[idx] for k, v in self.data.items()}),
+                attrs=self.fl_attrs[flight_id],
+                copy=copy,
+                fuel=self.fuel,
+            )
+            for flight_id, idx in indices.items()
         ]
 
     ###################################

pycontrails/core/flight.py

@@ -954,28 +954,13 @@ class Flight(GeoVectorDataset):
         # STEP 3: Set the time index, and sort it
         df = df.set_index("time", verify_integrity=True).sort_index()
 
-        # STEP 4: Some adhoc code for dealing with antimeridian.
-        # Idea: A flight likely crosses the antimeridian if
-        #   `min_pos > 90` and `max_neg < -90`
-        # This is not foolproof: it assumes the full trajectory will not
-        # span more than 180 longitude degrees. There could be flights that
-        # violate this near the poles (but this would be very rare -- flights
-        # would instead wrap the other way). For this flights spanning the
-        # antimeridian, we translate them to a common "chart" away from the
-        # antimeridian (see variable `shift`), then apply the interpolation,
-        # then shift back to their original position.
-        lon = df["longitude"].to_numpy()
-        sign_ = np.sign(lon)
-        min_pos = np.min(lon[sign_ == 1.0], initial=np.inf)
-        max_neg = np.max(lon[sign_ == -1.0], initial=-np.inf)
-
-        if (180.0 - min_pos) + (180.0 + max_neg) < 180.0 and min_pos < np.inf and max_neg > -np.inf:
-            # In this case, we believe the flight crosses the antimeridian
-            shift = min_pos
-            # So we shift the longitude "chart"
+        # STEP 4: handle antimeridian crossings
+        # For flights spanning the antimeridian, we translate them to a
+        # common "chart" away from the antimeridian (see variable `shift`),
+        # then apply the interpolation, then shift back to their original position.
+        shift = self._antimeridian_shift()
+        if shift is not None:
             df["longitude"] = (df["longitude"] - shift) % 360.0
-        else:
-            shift = None
 
         # STEP 5: Resample flight to freq
         # Save altitudes to copy over - these just get rounded down in time.
@@ -1189,19 +1174,12 @@ class Flight(GeoVectorDataset):
         """
 
         # Check if flight crosses antimeridian line
+        # If it does, shift longitude chart to remove jump
         lon_ = self["longitude"]
         lat_ = self["latitude"]
-        sign_ = np.sign(lon_)
-        min_pos = np.min(lon_[sign_ == 1.0], initial=np.inf)
-        max_neg = np.max(lon_[sign_ == -1.0], initial=-np.inf)
-
-        if (180.0 - min_pos) + (180.0 + max_neg) < 180.0 and min_pos < np.inf and max_neg > -np.inf:
-            # In this case, we believe the flight crosses the antimeridian
-            shift = min_pos
-            # So we shift the longitude "chart"
+        shift = self._antimeridian_shift()
+        if shift is not None:
             lon_ = (lon_ - shift) % 360.0
-        else:
-            shift = None
 
         # Make a fake flight that flies at constant height so distance is just
         # distance traveled across groud
@@ -1262,6 +1240,55 @@ class Flight(GeoVectorDataset):
 
         return lat, lon, seg_idx
 
+    def _antimeridian_shift(self) -> float | None:
+        """Determine shift required for resampling trajectories that cross antimeridian.
+
+        Because flights sometimes span more than 180 degree longitude (for example,
+        when flight-level winds favor travel in a specific direction, typically eastward),
+        antimeridian crossings cannot reliably be detected by looking only at minimum
+        and maximum longitudes.
+
+        Instead, this function checks each flight segment for an antimeridian crossing,
+        and if it finds one returns the coordinate of a meridian that is not crossed by
+        the flight.
+
+        Returns
+        -------
+        float | None
+            Longitude shift for handling antimeridian crossings, or None if the
+            flight does not cross the antimeridian.
+        """
+
+        # logic for detecting crossings is consistent with _antimeridian_crossing,
+        # but implementation is separate to keep performance costs as low as possible
+        lon = self["longitude"]
+        if np.any(np.isnan(lon)):
+            warnings.warn("Anti-meridian crossings can't be reliably detected with nan longitudes")
+
+        s1 = (lon >= -180) & (lon <= -90)
+        s2 = (lon <= 180) & (lon >= 90)
+        jump12 = s1[:-1] & s2[1:]  # westward
+        jump21 = s2[:-1] & s1[1:]  # eastward
+        if not np.any(jump12 | jump21):
+            return None
+
+        # separate flight into segments that are east and west of crossings
+        net_westward = np.insert(np.cumsum(jump12.astype(int) - jump21.astype(int)), 0, 0)
+        max_westward = net_westward.max()
+        if max_westward - net_westward.min() > 1:
+            msg = "Cannot handle consecutive antimeridian crossings in the same direction"
+            raise ValueError(msg)
+        east = (net_westward == 0) if max_westward == 1 else (net_westward == -1)
+
+        # shift must be between maximum longitude east of crossings
+        # and minimum longitude west of crossings
+        shift_min = np.nanmax(lon[east])
+        shift_max = np.nanmin(lon[~east])
+        if shift_min >= shift_max:
+            msg = "Cannot handle flight that spans more than 360 degrees longitude"
+            raise ValueError(msg)
+        return (shift_min + shift_max) / 2
+
     def _geodesic_interpolation(self, geodesic_threshold: float) -> pd.DataFrame | None:
         """Geodesic interpolate between large gaps between waypoints.
 
@@ -1506,25 +1533,25 @@ class Flight(GeoVectorDataset):
 
         >>> # Build flight
         >>> df = pd.DataFrame()
-        >>> df['time'] = pd.date_range('2022-03-01T00', '2022-03-01T03', periods=11)
-        >>> df['longitude'] = np.linspace(-20, 20, 11)
-        >>> df['latitude'] = np.linspace(-20, 20, 11)
-        >>> df['altitude'] = np.linspace(9500, 10000, 11)
-        >>> fl = Flight(df).resample_and_fill('10s')
+        >>> df["time"] = pd.date_range("2022-03-01T00", "2022-03-01T03", periods=11)
+        >>> df["longitude"] = np.linspace(-20, 20, 11)
+        >>> df["latitude"] = np.linspace(-20, 20, 11)
+        >>> df["altitude"] = np.linspace(9500, 10000, 11)
+        >>> fl = Flight(df).resample_and_fill("10s")
 
         >>> # Intersect and attach
-        >>> fl["air_temperature"] = fl.intersect_met(met['air_temperature'])
+        >>> fl["air_temperature"] = fl.intersect_met(met["air_temperature"])
         >>> fl["air_temperature"]
-        array([235.94657007, 235.95766965, 235.96873412, ..., 234.59917962,
+        array([235.94657007, 235.55745645, 235.56709768, ..., 234.59917962,
                234.60387402, 234.60845312])
 
         >>> # Length (in meters) of waypoints whose temperature exceeds 236K
         >>> fl.length_met("air_temperature", threshold=236)
-        np.float64(4132178.159...)
+        np.float64(3589705.998...)
 
         >>> # Proportion (with respect to distance) of waypoints whose temperature exceeds 236K
         >>> fl.proportion_met("air_temperature", threshold=236)
-        np.float64(0.663552...)
+        np.float64(0.576...)
         """
         if key not in self.data:
             raise KeyError(f"Column {key} does not exist in data.")
@@ -1591,10 +1618,30 @@ class Flight(GeoVectorDataset):
         :class:`matplotlib.axes.Axes`
             Plot
         """
-        ax = self.dataframe.plot(x="longitude", y="latitude", legend=False, **kwargs)
+        kwargs.setdefault("legend", False)
+        ax = self.dataframe.plot(x="longitude", y="latitude", **kwargs)
         ax.set(xlabel="longitude", ylabel="latitude")
         return ax
 
+    def plot_profile(self, **kwargs: Any) -> matplotlib.axes.Axes:
+        """Plot flight trajectory time-altitude values.
+
+        Parameters
+        ----------
+        **kwargs : Any
+            Additional plot properties to passed to `pd.DataFrame.plot`
+
+        Returns
+        -------
+        :class:`matplotlib.axes.Axes`
+            Plot
+        """
+        kwargs.setdefault("legend", False)
+        df = self.dataframe.assign(altitude_ft=self.altitude_ft)
+        ax = df.plot(x="time", y="altitude_ft", **kwargs)
+        ax.set(xlabel="time", ylabel="altitude_ft")
+        return ax
+
 
 def _return_linestring(data: dict[str, npt.NDArray[np.float64]]) -> list[list[float]]:
     """Return list of coordinates for geojson constructions.
@@ -1631,18 +1678,14 @@ def _antimeridian_index(longitude: pd.Series, crs: str = "EPSG:4326") -> list[in
 
     Returns
     -------
-    int
-        Index after jump or -1
+    list[int]
+        Indices after jump, or empty list of flight does not cross antimeridian.
 
     Raises
     ------
     ValueError
         CRS is not supported.
-        Flight crosses antimeridian several times.
     """
-    # FIXME: This logic here is somewhat outdated - the _interpolate_altitude
-    # method handles this somewhat more reliably
-    # This function should get updated to follow the logic there.
     # WGS84
     if crs in ["EPSG:4326"]:
         l1 = (-180.0, -90.0)
@@ -1878,7 +1921,7 @@ def _altitude_interpolation_climb_descend_middle(
     s = pd.Series(altitude)
 
     # Check to see if we have gaps greater than two hours
-    step_threshold = 120.0 * freq / np.timedelta64(1, "m")
+    step_threshold = np.timedelta64(2, "h") / freq
     step_groups = na_group_size > step_threshold
     if np.any(step_groups):
         # If there are gaps greater than two hours, step through one by one
@@ -2214,16 +2257,14 @@ def segment_rocd(
     if air_temperature is None:
         return out
 
-    else:
-        altitude_m = units.ft_to_m(altitude_ft)
-        T_isa = units.m_to_T_isa(altitude_m)
+    altitude_m = units.ft_to_m(altitude_ft)
+    T_isa = units.m_to_T_isa(altitude_m)
 
-        T_correction = np.empty_like(altitude_ft)
-        T_correction[:-1] = (0.5 * (air_temperature[:-1] + air_temperature[1:])) / (
-            0.5 * (T_isa[:-1] + T_isa[1:])
-        )
-        T_correction[-1] = np.nan
-        return T_correction * out
+    T_correction = np.empty_like(altitude_ft)
+    T_correction[:-1] = (air_temperature[:-1] + air_temperature[1:]) / (T_isa[:-1] + T_isa[1:])
+    T_correction[-1] = np.nan
+
+    return T_correction * out
 
 
 def _resample_to_freq(df: pd.DataFrame, freq: str) -> tuple[pd.DataFrame, pd.DatetimeIndex]:

pycontrails/core/interpolation.py

@@ -215,7 +215,8 @@ class PycontrailsRegularGridInterpolator(scipy.interpolate.RegularGridInterpolat
 
         if ndim == 1:
             # np.interp could be better ... although that may also promote the dtype
-            return rgi_cython.evaluate_linear_1d(values, indices, norm_distances, out)
+            # 1-d view is required for evaluate_linear_1d
+            return rgi_cython.evaluate_linear_1d(values, indices[0, :], norm_distances[0, :], out)
 
         msg = f"Invalid number of dimensions: {ndim}"
         raise ValueError(msg)