pycontrails 0.49.5__cp311-cp311-macosx_10_9_x86_64.whl → 0.50.1__cp311-cp311-macosx_10_9_x86_64.whl

pycontrails/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.49.5'
-__version_tuple__ = version_tuple = (0, 49, 5)
+__version__ = version = '0.50.1'
+__version_tuple__ = version_tuple = (0, 50, 1)

pycontrails/core/datalib.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import abc
-import dataclasses
 import hashlib
 import logging
 import pathlib
@@ -109,6 +108,11 @@ def parse_pressure_levels(
 ) -> list[int]:
     """Check input pressure levels are consistent type and ensure levels exist in ECMWF data source.
 
+    .. versionchanged:: 0.50.0
+
+        The returned pressure levels are now sorted. Pressure levels must be unique.
+        Raises ValueError if pressure levels have mixed signs.
+
     Parameters
     ----------
     pressure_levels : PressureLevelInput
@@ -127,18 +131,31 @@ def parse_pressure_levels(
     ValueError
         Raises ValueError if pressure level is not supported by ECMWF data source
     """
-    # ensure pressure_levels is list-like
+    # Ensure pressure_levels is array-like
     if isinstance(pressure_levels, (int, float)):
         pressure_levels = [pressure_levels]
 
-    # Cast array-like to list of ints
-    out = np.asarray(pressure_levels, dtype=int).tolist()
+    # Cast array-like to int dtype and sort
+    arr = np.asarray(pressure_levels, dtype=int)
+    arr.sort()
 
-    # ensure pressure levels are valid
-    for pl in out:
-        if supported and pl not in supported:
-            msg = f"Pressure level {pl} is not supported. Supported levels: {supported}"
-            raise ValueError(msg)
+    # If any values are non-positive, the entire array should be [-1]
+    if np.any(arr <= 0) and not np.array_equal(arr, [-1]):
+        msg = f"Pressure levels must be all positive or all -1, got {arr}"
+        raise ValueError(msg)
+
+    # Ensure pressure levels are unique
+    if np.any(np.diff(arr) == 0):
+        msg = f"Pressure levels must be unique, got {arr}"
+        raise ValueError(msg)
+
+    out = arr.tolist()
+    if supported is None:
+        return out
+
+    if missing := set(out).difference(supported):
+        msg = f"Pressure levels {sorted(missing)} are not supported. Supported levels: {supported}"
+        raise ValueError(msg)
 
     return out
 
@@ -146,6 +163,11 @@ def parse_pressure_levels(
 def parse_variables(variables: VariableInput, supported: list[MetVariable]) -> list[MetVariable]:
     """Parse input variables.
 
+    .. versionchanged:: 0.50.0
+
+        The output is no longer copied. Each :class:`MetVariable` is a frozen dataclass,
+        so copying is unnecessary.
+
     Parameters
     ----------
     variables : VariableInput
@@ -178,35 +200,31 @@ def parse_variables(variables: VariableInput, supported: list[MetVariable]) -> l
     else:
         parsed_variables = variables
 
-    # unpack dict of supported str values from supported
     short_names = {v.short_name: v for v in supported}
     standard_names = {v.standard_name: v for v in supported}
     long_names = {v.long_name: v for v in supported}
-
-    # unpack dict of support int values from supported
     ecmwf_ids = {v.ecmwf_id: v for v in supported}
     grib1_ids = {v.grib1_id: v for v in supported}
+    supported_set = set(supported)
 
     for var in parsed_variables:
         matched = _find_match(
             var,
-            supported,
+            supported_set,
             ecmwf_ids,  # type: ignore[arg-type]
             grib1_ids,  # type: ignore[arg-type]
             short_names,
             standard_names,
             long_names,  # type: ignore[arg-type]
         )
-
-        # "replace" copies dataclass
-        met_var_list.append(dataclasses.replace(matched))
+        met_var_list.append(matched)
 
     return met_var_list
 
 
 def _find_match(
     var: VariableInput,
-    supported: list[MetVariable],
+    supported: set[MetVariable],
     ecmwf_ids: dict[int, MetVariable],
     grib1_ids: dict[int, MetVariable],
     short_names: dict[str, MetVariable],
@@ -215,9 +233,8 @@ def _find_match(
 ) -> MetVariable:
     """Find a match for input variable in supported."""
 
-    if isinstance(var, MetVariable):
-        if var in supported:
-            return var
+    if isinstance(var, MetVariable) and var in supported:
+        return var
 
     # list of MetVariable options
     # here we extract the first MetVariable in var that is supported
@@ -230,21 +247,19 @@ def _find_match(
             if v in supported:
                 return v
 
-    # int code
     elif isinstance(var, int):
-        if var in ecmwf_ids:
-            return ecmwf_ids[var]
-        if var in grib1_ids:
-            return grib1_ids[var]
+        if ret := ecmwf_ids.get(var):
+            return ret
+        if ret := grib1_ids.get(var):
+            return ret
 
-    # string reference
     elif isinstance(var, str):
-        if var in short_names:
-            return short_names[var]
-        if var in standard_names:
-            return standard_names[var]
-        if var in long_names:
-            return long_names[var]
+        if ret := short_names.get(var):
+            return ret
+        if ret := standard_names.get(var):
+            return ret
+        if ret := long_names.get(var):
+            return ret
 
     msg = f"{var} is not in supported parameters. Supported parameters include: {standard_names}"
     raise ValueError(msg)
@@ -395,6 +410,14 @@ class MetDataSource(abc.ABC):
         """
         return [v.standard_name for v in self.variables]
 
+    @property
+    def is_single_level(self) -> bool:
+        """Return True if the datasource is single level data.
+
+        .. versionadded:: 0.50.0
+        """
+        return self.pressure_levels == [-1]
+
     @property
     def pressure_level_variables(self) -> list[MetVariable]:
         """Parameters available from data source.
@@ -426,10 +449,9 @@ class MetDataSource(abc.ABC):
         list[MetVariable] | None
             List of MetVariable available in datasource
         """
-        if self.pressure_levels != [-1]:
-            return self.pressure_level_variables
-
-        return self.single_level_variables
+        return (
+            self.single_level_variables if self.is_single_level else self.pressure_level_variables
+        )
 
     @property
     def supported_pressure_levels(self) -> list[int] | None:
@@ -497,7 +519,7 @@ class MetDataSource(abc.ABC):
     def open_metdataset(
         self,
         dataset: xr.Dataset | None = None,
-        xr_kwargs: dict[str, int] | None = None,
+        xr_kwargs: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> MetDataset:
         """Open MetDataset from data source.
@@ -510,7 +532,7 @@ class MetDataSource(abc.ABC):
         dataset : xr.Dataset | None, optional
             Input :class:`xr.Dataset` loaded manually.
             The dataset must have the same format as the original data source API or files.
-        xr_kwargs : dict[str, int] | None, optional
+        xr_kwargs : dict[str, Any] | None, optional
             Dictionary of keyword arguments passed into :func:`xarray.open_mfdataset`
             when opening files. Examples include "chunks", "engine", "parallel", etc.
             Ignored if ``dataset`` is input.

pycontrails/core/flight.py

@@ -787,6 +787,13 @@ class Flight(GeoVectorDataset):
         Waypoints are resampled according to the frequency ``freq``. Values for :attr:`data`
         columns ``longitude``, ``latitude``, and ``altitude`` are interpolated.
 
+        Resampled waypoints will include all multiples of ``freq`` between the flight
+        start and end time. For example, when resampling to a frequency of 1 minute,
+        a flight that starts at 2020/1/1 00:00:59 and ends at 2020/1/1 00:01:01
+        will return a single waypoint at 2020/1/1 00:01:00, whereas a flight that
+        starts at 2020/1/1 00:01:01 and ends at 2020/1/1 00:01:59 will return an empty
+        flight.
+
         Parameters
         ----------
         freq : str, optional
@@ -1349,8 +1356,8 @@ class Flight(GeoVectorDataset):
         >>> # Intersect and attach
         >>> fl["air_temperature"] = fl.intersect_met(met['air_temperature'])
         >>> fl["air_temperature"]
-        array([235.94658, 235.95767, 235.96873, ..., 234.59918, 234.60388,
-               234.60846], dtype=float32)
+        array([235.94657007, 235.95766965, 235.96873412, ..., 234.59917962,
+               234.60387402, 234.60845312])
 
         >>> # Length (in meters) of waypoints whose temperature exceeds 236K
         >>> fl.length_met("air_temperature", threshold=236)
@@ -2063,11 +2070,9 @@ def _resample_to_freq(df: pd.DataFrame, freq: str) -> tuple[pd.DataFrame, pd.Dat
 
     # Manually create a new index that includes all the original index values
     # and the resampled-to-freq index values.
-    t0 = df.index[0]
+    t0 = df.index[0].ceil(freq)
     t1 = df.index[-1]
-    t = pd.date_range(t0, t1, freq=freq, name="time").floor(freq)
-    if t[0] < t0:
-        t = t[1:]
+    t = pd.date_range(t0, t1, freq=freq, name="time")
 
     concat_arr = np.concatenate([df.index, t])
     concat_arr = np.unique(concat_arr)

pycontrails/core/interpolation.py

@@ -71,7 +71,9 @@ class PycontrailsRegularGridInterpolator(scipy.interpolate.RegularGridInterpolat
 
         self.grid = points
         self.values = values
-        self.method = method
+        # TODO: consider supporting updated tensor-product spline methods
+        # see https://github.com/scipy/scipy/releases/tag/v1.13.0
+        self.method = _pick_method(scipy.__version__, method)
         self.bounds_error = bounds_error
         self.fill_value = fill_value
 
@@ -219,6 +221,42 @@ class PycontrailsRegularGridInterpolator(scipy.interpolate.RegularGridInterpolat
         raise ValueError(msg)
 
 
+def _pick_method(scipy_version: str, method: str) -> str:
+    """Select an interpolation method.
+
+    For scipy versions 1.13.0 and later, fall back on legacy implementations
+    of tensor-product spline methods. The default implementations in 1.13.0
+    and later are incompatible with this class.
+
+    Parameters
+    ----------
+    scipy_version : str
+        scipy version (major.minor.patch)
+
+    method : str
+        Interpolation method. Passed into :class:`scipy.interpolate.RegularGridInterpolator`
+        as-is unless ``scipy_version`` is 1.13.0 or later and ``method`` is ``"slinear"``,
+        ``"cubic"``, or ``"quintic"``. In this case, ``"_legacy"`` is appended to ``method``.
+
+    Returns
+    -------
+    str
+        Interpolation method adjusted for compatibility with this class.
+    """
+    try:
+        version = scipy_version.split(".")
+        major = int(version[0])
+        minor = int(version[1])
+    except (IndexError, ValueError) as exc:
+        msg = f"Failed to parse major and minor version from {scipy_version}"
+        raise ValueError(msg) from exc
+
+    reimplemented_methods = ["slinear", "cubic", "quintic"]
+    if major > 1 or (major == 1 and minor >= 13) and method in reimplemented_methods:
+        return method + "_legacy"
+    return method
+
+
 def _floatize_time(
     time: npt.NDArray[np.datetime64], offset: np.datetime64
 ) -> npt.NDArray[np.float64]:

pycontrails/core/met.py

@@ -674,13 +674,10 @@ class MetDataset(MetBase):
     >>> da = mda.data  # Underlying `xarray` object
 
     >>> # Check out a few values
-    >>> da[5:10, 5:10, 1, 1].values
-    array([[224.0896 , 224.41374, 224.75946, 225.16237, 225.60507],
-           [224.09457, 224.42038, 224.76526, 225.16817, 225.61089],
-           [224.10037, 224.42618, 224.77106, 225.17314, 225.61586],
-           [224.10617, 224.43282, 224.7777 , 225.17812, 225.62166],
-           [224.11115, 224.44028, 224.7835 , 225.18393, 225.62663]],
-          dtype=float32)
+    >>> da[5:8, 5:8, 1, 1].values
+    array([[224.08959005, 224.41374427, 224.75945349],
+           [224.09456429, 224.42037658, 224.76525676],
+           [224.10036756, 224.42617985, 224.77106004]])
 
     >>> # Mean temperature over entire array
     >>> da.mean().load().item()
@@ -1065,8 +1062,8 @@ class MetDataset(MetBase):
 
         """
         coords_keys = self.data.dims
-        variables = self.indexes
-        coords_vals = [variables[key].values for key in coords_keys]
+        indexes = self.indexes
+        coords_vals = [indexes[key].values for key in coords_keys]
         coords_meshes = np.meshgrid(*coords_vals, indexing="ij")
         raveled_coords = (mesh.ravel() for mesh in coords_meshes)
         data = dict(zip(coords_keys, raveled_coords))
@@ -1181,12 +1178,12 @@ class MetDataset(MetBase):
         level: npt.ArrayLike | float,
         time: npt.ArrayLike | np.datetime64,
     ) -> MetDataset:
-        """Create a :class:`MetDataset` containing a coordinate skeleton from coordinate arrays.
+        r"""Create a :class:`MetDataset` containing a coordinate skeleton from coordinate arrays.
 
         Parameters
         ----------
         longitude, latitude : npt.ArrayLike | float
-            Horizontal coordinates, in [:math:`degrees`]
+            Horizontal coordinates, in [:math:`\deg`]
         level : npt.ArrayLike | float
             Vertical coordinate, in [:math:`hPa`]
         time: npt.ArrayLike | np.datetime64,
@@ -1618,15 +1615,15 @@ class MetDataArray(MetBase):
 
         >>> # Interpolation at a grid point agrees with value
         >>> mda.interpolate(1, 2, 300, np.datetime64('2022-03-01T14:00'))
-        array([241.91974], dtype=float32)
+        array([241.91972984])
 
         >>> da = mda.data
         >>> da.sel(longitude=1, latitude=2, level=300, time=np.datetime64('2022-03-01T14')).item()
-        241.91974
+        241.9197298421629
 
         >>> # Interpolation off grid
         >>> mda.interpolate(1.1, 2.1, 290, np.datetime64('2022-03-01 13:10'))
-        array([239.83794], dtype=float32)
+        array([239.83793798])
 
         >>> # Interpolate along path
         >>> longitude = np.linspace(1, 2, 10)
@@ -1634,8 +1631,9 @@ class MetDataArray(MetBase):
         >>> level = np.linspace(200, 300, 10)
         >>> time = pd.date_range("2022-03-01T14", periods=10, freq="5min")
         >>> mda.interpolate(longitude, latitude, level, time)
-        array([220.44348, 223.089  , 225.7434 , 228.41643, 231.10858, 233.54858,
-               235.71506, 237.86479, 239.99275, 242.10793], dtype=float32)
+        array([220.44347694, 223.08900738, 225.74338924, 228.41642088,
+               231.10858599, 233.54857391, 235.71504913, 237.86478872,
+               239.99274623, 242.10792167])
         """
         # Load if necessary
         if not self.in_memory:

pycontrails/core/met_var.py

@@ -76,12 +76,12 @@ class MetVariable:
 
     @property
     def ecmwf_link(self) -> str | None:
-        """Database link in the ECMWF Paramter Database if :attr:`ecmwf_id` is defined.
+        """Database link in the ECMWF Parameter Database if :attr:`ecmwf_id` is defined.
 
         Returns
         -------
         str
-            Database link in the ECMWF Paramter Database
+            Database link in the ECMWF Parameter Database
         """
         return (
             f"https://apps.ecmwf.int/codes/grib/param-db?id={self.ecmwf_id}"

pycontrails/core/models.py

@@ -440,17 +440,21 @@ class Model(ABC):
             # Return dataset with the same coords as self.met, but empty data_vars
             return MetDataset(xr.Dataset(coords=self.met.data.coords))
 
+        copy_source = self.params["copy_source"]
+
         # Turn Sequence into Fleet
         if isinstance(source, Sequence):
-            # TODO: fix type guard here
-            return Fleet.from_seq(source, copy=self.params["copy_source"])
+            if not copy_source:
+                msg = "Parameter copy_source=False is not supported for Sequence[Flight] source"
+                raise ValueError(msg)
+            return Fleet.from_seq(source)
 
         # Raise error if source is not a MetDataset or GeoVectorDataset
         if not isinstance(source, (MetDataset, GeoVectorDataset)):
             msg = f"Unknown source type: {type(source)}"
             raise TypeError(msg)
 
-        if self.params["copy_source"]:
+        if copy_source:
             source = source.copy()
 
         if not isinstance(source, Flight):

pycontrails/core/vector.py

@@ -1694,12 +1694,14 @@ class GeoVectorDataset(VectorDataset):
 
         >>> # Intersect
         >>> fl.intersect_met(met['air_temperature'], method='nearest')
-        array([231.6297 , 230.72604, 232.2432 , 231.88339, 231.0643 , 231.59073,
-               231.65126, 231.93065, 232.03345, 231.65955], dtype=float32)
+        array([231.62969892, 230.72604651, 232.24318771, 231.88338483,
+               231.06429438, 231.59073409, 231.65125393, 231.93064004,
+               232.03344087, 231.65954432])
 
         >>> fl.intersect_met(met['air_temperature'], method='linear')
-        array([225.77794, 225.13908, 226.23122, 226.31831, 225.56102, 225.81192,
-               226.03194, 226.22057, 226.0377 , 225.63226], dtype=float32)
+        array([225.77794552, 225.13908414, 226.231218  , 226.31831528,
+               225.56102321, 225.81192149, 226.03192642, 226.22056121,
+               226.03770174, 225.63226188])
 
         >>> # Interpolate and attach to `Flight` instance
         >>> for key in met:
@@ -1708,11 +1710,11 @@ class GeoVectorDataset(VectorDataset):
         >>> # Show the final three columns of the dataframe
         >>> fl.dataframe.iloc[:, -3:].head()
                          time  air_temperature  specific_humidity
-        0 2022-03-01 00:00:00       225.777939           0.000132
+        0 2022-03-01 00:00:00       225.777946           0.000132
         1 2022-03-01 00:13:20       225.139084           0.000132
-        2 2022-03-01 00:26:40       226.231216           0.000107
-        3 2022-03-01 00:40:00       226.318314           0.000171
-        4 2022-03-01 00:53:20       225.561020           0.000109
+        2 2022-03-01 00:26:40       226.231218           0.000107
+        3 2022-03-01 00:40:00       226.318315           0.000171
+        4 2022-03-01 00:53:20       225.561022           0.000109
 
         """
         # Override use_indices in certain situations
@@ -1899,19 +1901,19 @@ class GeoVectorDataset(VectorDataset):
         MetDataset | MetDataArray
             Copy of downselected MetDataset or MetDataArray.
         """
-        variables = met.indexes
+        indexes = met.indexes
         lon_slice = coordinates.slice_domain(
-            variables["longitude"].to_numpy(),
+            indexes["longitude"].to_numpy(),
             self["longitude"],
             buffer=longitude_buffer,
         )
         lat_slice = coordinates.slice_domain(
-            variables["latitude"].to_numpy(),
+            indexes["latitude"].to_numpy(),
             self["latitude"],
             buffer=latitude_buffer,
         )
         time_slice = coordinates.slice_domain(
-            variables["time"].to_numpy(),
+            indexes["time"].to_numpy(),
             self["time"],
             buffer=time_buffer,
         )
@@ -1921,7 +1923,7 @@ class GeoVectorDataset(VectorDataset):
             level_slice = slice(None)
         else:
             level_slice = coordinates.slice_domain(
-                variables["level"].to_numpy(),
+                indexes["level"].to_numpy(),
                 self.level,
                 buffer=level_buffer,
             )

pycontrails/datalib/ecmwf/__init__.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from pycontrails.datalib.ecmwf.arco_era5 import ARCOERA5
 from pycontrails.datalib.ecmwf.era5 import ERA5
 from pycontrails.datalib.ecmwf.hres import HRES
 from pycontrails.datalib.ecmwf.ifs import IFS
@@ -11,6 +12,7 @@ from pycontrails.datalib.ecmwf.variables import (
     SURFACE_VARIABLES,
     CloudAreaFraction,
     CloudAreaFractionInLayer,
+    Divergence,
     PotentialVorticity,
     RelativeHumidity,
     RelativeVorticity,
@@ -23,11 +25,13 @@ from pycontrails.datalib.ecmwf.variables import (
 )
 
 __all__ = [
+    "ARCOERA5",
     "ERA5",
     "HRES",
     "IFS",
     "CloudAreaFraction",
     "CloudAreaFractionInLayer",
+    "Divergence",
     "PotentialVorticity",
     "RelativeHumidity",
     "RelativeVorticity",