pycontrails 0.54.4__cp313-cp313-macosx_11_0_arm64.whl → 0.54.6__cp313-cp313-macosx_11_0_arm64.whl

pycontrails/core/vector.py

@@ -37,6 +37,8 @@ logger = logging.getLogger(__name__)
 class AttrDict(dict[str, Any]):
     """Thin wrapper around dict to warn when setting a key that already exists."""
 
+    __slots__ = ()
+
     def __setitem__(self, k: str, v: Any) -> None:
         """Warn when setting values that already contain values.
 
@@ -85,7 +87,7 @@ class VectorDataDict(dict[str, np.ndarray]):
     Parameters
     ----------
     data : dict[str, np.ndarray], optional
-        Dictionary input
+        Dictionary input. A shallow copy is always made.
     """
 
     __slots__ = ("_size",)
@@ -130,8 +132,8 @@ class VectorDataDict(dict[str, np.ndarray]):
     def __delitem__(self, k: str) -> None:
         super().__delitem__(k)
 
-        # if not data keys left, set size to 0
-        if not len(self):
+        # if no keys remain, delete _size attribute
+        if not self:
             del self._size
 
     def setdefault(self, k: str, default: npt.ArrayLike | None = None) -> np.ndarray:
@@ -191,9 +193,9 @@ class VectorDataDict(dict[str, np.ndarray]):
         super().update(kwargs_arr)
 
     def _validate_array(self, arr: np.ndarray) -> None:
-        """Ensure that `arr` is compatible with instance.
+        """Ensure that ``arr`` is compatible (1 dimensional of equal size) with instance.
 
-        Set attribute `_size` if it has not yet been defined.
+        Set attribute ``_size`` if it has not yet been defined.
 
         Parameters
         ----------
@@ -203,34 +205,34 @@ class VectorDataDict(dict[str, np.ndarray]):
         Raises
         ------
         ValueError
-            If `arr` is not compatible with instance.
+            If ``arr`` is not compatible with instance.
         """
         if arr.ndim != 1:
             raise ValueError("All np.arrays must have dimension 1.")
 
         size = getattr(self, "_size", 0)
-        if size != 0:
-            if arr.size != size:
-                raise ValueError(f"Incompatible array sizes: {arr.size} and {size}.")
-        else:
+        if not size:
             self._size = arr.size
+            return
+
+        if arr.size != size:
+            raise ValueError(f"Incompatible array sizes: {arr.size} and {size}.")
 
 
-def _empty_vector_dict(keys: Iterable[str]) -> VectorDataDict:
-    """Create instance of VectorDataDict with variables defined by `keys` and size 0.
+def _empty_vector_dict(keys: Iterable[str]) -> dict[str, np.ndarray]:
+    """Create a dictionary with keys defined by ``keys`` and empty arrays.
 
     Parameters
     ----------
     keys : Iterable[str]
-        Keys to include in empty VectorDataset instance.
+        Keys to include in dictionary.
 
     Returns
     -------
-    VectorDataDict
-        Empty :class:`VectorDataDict` instance.
+    dict[str, np.ndarray]
+        Dictionary with empty arrays.
     """
-    keys = keys or ()
-    data = VectorDataDict({key: np.array([]) for key in keys})
+    data = {key: np.array([]) for key in keys}
 
     # The default dtype is float64
     # Time is special and should have a non-default dtype of datetime64[ns]
@@ -245,14 +247,15 @@ class VectorDataset:
 
     Parameters
     ----------
-    data : dict[str, npt.ArrayLike] | pd.DataFrame | VectorDataDict | VectorDataset | None, optional
-        Initial data, by default None
-    attrs : dict[str, Any] | AttrDict, optional
-        Dictionary of attributes, by default None
+    data : dict[str, npt.ArrayLike] | pd.DataFrame | VectorDataset | None, optional
+        Initial data, by default None. A shallow copy is always made. Use the ``copy``
+        parameter to copy the underlying array data.
+    attrs : dict[str, Any] | None, optional
+        Dictionary of attributes, by default None. A shallow copy is always made.
     copy : bool, optional
-        Copy data on class creation, by default True
+        Copy individual arrays on instantiation, by default True.
     **attrs_kwargs : Any
-        Additional attributes passed as keyword arguments
+        Additional attributes passed as keyword arguments.
 
     Raises
     ------
@@ -262,24 +265,22 @@ class VectorDataset:
 
     __slots__ = ("attrs", "data")
 
-    #: Vector data with labels as keys and :class:`numpy.ndarray` as values
-    data: VectorDataDict
-
     #: Generic dataset attributes
     attrs: AttrDict
 
+    #: Vector data with labels as keys and :class:`numpy.ndarray` as values
+    data: VectorDataDict
+
     def __init__(
         self,
-        data: (
-            dict[str, npt.ArrayLike] | pd.DataFrame | VectorDataDict | VectorDataset | None
-        ) = None,
+        data: dict[str, npt.ArrayLike] | pd.DataFrame | VectorDataset | None = None,
         *,
-        attrs: dict[str, Any] | AttrDict | None = None,
+        attrs: dict[str, Any] | None = None,
         copy: bool = True,
         **attrs_kwargs: Any,
     ) -> None:
-        # Set data
-        # --------
+        # Set data: always shallow copy
+        # -----------------------------
 
         # Casting from one VectorDataset type to another
         # e.g., flight = Flight(...); vector = VectorDataset(flight)
@@ -288,7 +289,7 @@ class VectorDataset:
             if copy:
                 self.data = VectorDataDict({k: v.copy() for k, v in data.data.items()})
             else:
-                self.data = data.data
+                self.data = VectorDataDict(data.data)
 
         elif data is None:
             self.data = VectorDataDict()
@@ -307,31 +308,45 @@ class VectorDataset:
                 data["time"] = time.to_numpy(copy=copy)
                 self.data = VectorDataDict(data)
 
-        elif isinstance(data, VectorDataDict):
-            if copy:
-                self.data = VectorDataDict({k: v.copy() for k, v in data.items()})
-            else:
-                self.data = data
-
         # For anything else, we assume it is a dictionary of array-like and attach it
         else:
             self.data = VectorDataDict({k: np.array(v, copy=copy) for k, v in data.items()})
 
-        # Set attributes
-        # --------------
+        # Set attributes: always shallow copy
+        # -----------------------------------
+
+        self.attrs = AttrDict(attrs or {})  # type: ignore[arg-type]
+        self.attrs.update(attrs_kwargs)
+
+    @classmethod
+    def _from_fastpath(
+        cls,
+        data: dict[str, np.ndarray],
+        attrs: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Self:
+        """Create new instance from consistent data.
 
-        if attrs is None:
-            self.attrs = AttrDict()
+        This is a low-level method that bypasses the standard constructor in certain
+        special cases. It is intended for internal use only.
 
-        elif isinstance(attrs, AttrDict) and not copy:
-            self.attrs = attrs
+        In essence, this method skips any validation from __init__ and directly sets
+        ``data`` and ``attrs``. This is useful when creating a new instance from an existing
+        instance the data has already been validated.
+        """
+        obj = cls.__new__(cls)
 
-        #  shallow copy if dict
-        else:
-            self.attrs = AttrDict(attrs.copy())
+        obj.data = VectorDataDict(data)
+        obj.attrs = AttrDict(attrs or {})
 
-        # update with kwargs
-        self.attrs.update(attrs_kwargs)
+        for key, value in kwargs.items():
+            try:
+                setattr(obj, key, value)
+            # If key not present in __slots__ of class (or parents), it's intended for attrs
+            except AttributeError:
+                obj.attrs[key] = value
+
+        return obj
 
     # ------------
     # dict-like methods
@@ -663,6 +678,13 @@ class VectorDataset:
         8  15  18
 
         """
+        if cls not in (VectorDataset, GeoVectorDataset):
+            msg = (
+                "Method 'sum' is only available on 'VectorDataset' and 'GeoVectorDataset'. "
+                "To sum 'Flight' instances, use 'Fleet.from_seq'."
+            )
+            raise TypeError(msg)
+
         vectors = [v for v in vectors if v is not None]  # remove None values
 
         if not vectors:
@@ -693,10 +715,9 @@ class VectorDataset:
             return np.concatenate(values)
 
         data = {key: concat(key) for key in keys}
+        attrs = vectors[0].attrs if infer_attrs else None
 
-        if infer_attrs:
-            return cls(data, attrs=vectors[0].attrs, copy=False)
-        return cls(data, copy=False)
+        return cls._from_fastpath(data, attrs)
 
     def __eq__(self, other: object) -> bool:
         """Determine if two instances are equal.
@@ -803,7 +824,8 @@ class VectorDataset:
         Self
             Copy of class
         """
-        return type(self)(data=self.data, attrs=self.attrs, copy=True, **kwargs)
+        data = {key: value.copy() for key, value in self.data.items()}
+        return type(self)._from_fastpath(data, self.attrs, **kwargs)
 
     def select(self: VectorDataset, keys: Iterable[str], copy: bool = True) -> VectorDataset:
         """Return new class instance only containing specified keys.
@@ -823,8 +845,8 @@ class VectorDataset:
             Note that this method always returns a :class:`VectorDataset`, even if
             the calling class is a proper subclass of :class:`VectorDataset`.
         """
-        data = {key: self[key] for key in keys}
-        return VectorDataset(data=data, attrs=self.attrs, copy=copy)
+        data = {key: np.array(self[key], copy=copy) for key in keys}
+        return VectorDataset._from_fastpath(data, self.attrs)
 
     def filter(self, mask: npt.NDArray[np.bool_], copy: bool = True, **kwargs: Any) -> Self:
         """Filter :attr:`data` according to a boolean array ``mask``.
@@ -856,8 +878,8 @@ class VectorDataset:
         if mask.dtype != bool:
             raise TypeError("Parameter `mask` must be a boolean array.")
 
-        data = {key: value[mask] for key, value in self.data.items()}
-        return type(self)(data=data, attrs=self.attrs, copy=copy, **kwargs)
+        data = {key: np.array(value[mask], copy=copy) for key, value in self.data.items()}
+        return type(self)._from_fastpath(data, self.attrs, **kwargs)
 
     def sort(self, by: str | list[str]) -> Self:
         """Sort data by key(s).
@@ -1116,7 +1138,7 @@ class VectorDataset:
         cls,
         keys: Iterable[str],
         attrs: dict[str, Any] | None = None,
-        **attrs_kwargs: Any,
+        **kwargs: Any,
     ) -> Self:
         """Create instance with variables defined by ``keys`` and size 0.
 
@@ -1129,15 +1151,16 @@ class VectorDataset:
             Keys to include in empty VectorDataset instance.
         attrs : dict[str, Any] | None, optional
             Attributes to attach instance.
-        **attrs_kwargs : Any
-            Define attributes as keyword arguments.
+        **kwargs : Any
+            Additional keyword arguments passed into the constructor of the returned class.
 
         Returns
         -------
         Self
             Empty VectorDataset instance.
         """
-        return cls(data=_empty_vector_dict(keys or set()), attrs=attrs, copy=False, **attrs_kwargs)
+        data = _empty_vector_dict(keys)
+        return cls._from_fastpath(data, attrs, **kwargs)
 
     @classmethod
     def from_dict(cls, obj: dict[str, Any], copy: bool = True, **obj_kwargs: Any) -> Self:
@@ -1216,7 +1239,7 @@ class GeoVectorDataset(VectorDataset):
 
     Parameters
     ----------
-    data : dict[str, npt.ArrayLike] | pd.DataFrame | VectorDataDict | VectorDataset | None, optional
+    data : dict[str, npt.ArrayLike] | pd.DataFrame | VectorDataset | None, optional
         Data dictionary or :class:`pandas.DataFrame` .
         Must include keys/columns ``time``, ``latitude``, ``longitude``, ``altitude`` or ``level``.
         Keyword arguments for ``time``, ``latitude``, ``longitude``, ``altitude`` or ``level``
@@ -1269,9 +1292,7 @@ class GeoVectorDataset(VectorDataset):
 
     def __init__(
         self,
-        data: (
-            dict[str, npt.ArrayLike] | pd.DataFrame | VectorDataDict | VectorDataset | None
-        ) = None,
+        data: dict[str, npt.ArrayLike] | pd.DataFrame | VectorDataset | None = None,
         *,
         longitude: npt.ArrayLike | None = None,
         latitude: npt.ArrayLike | None = None,
@@ -1279,7 +1300,7 @@ class GeoVectorDataset(VectorDataset):
         altitude_ft: npt.ArrayLike | None = None,
         level: npt.ArrayLike | None = None,
         time: npt.ArrayLike | None = None,
-        attrs: dict[str, Any] | AttrDict | None = None,
+        attrs: dict[str, Any] | None = None,
         copy: bool = True,
         **attrs_kwargs: Any,
     ) -> None:
@@ -1293,7 +1314,10 @@ class GeoVectorDataset(VectorDataset):
             and time is None
         ):
             keys = *self.required_keys, "altitude"
-            data = _empty_vector_dict(keys)
+            self.data = VectorDataDict(_empty_vector_dict(keys))
+            self.attrs = AttrDict(attrs or {})  # type: ignore[arg-type]
+            self.attrs.update(attrs_kwargs)
+            return
 
         super().__init__(data=data, attrs=attrs, copy=copy, **attrs_kwargs)
 
@@ -1819,7 +1843,6 @@ class GeoVectorDataset(VectorDataset):
         latitude_buffer: tuple[float, float] = ...,
         level_buffer: tuple[float, float] = ...,
         time_buffer: tuple[np.timedelta64, np.timedelta64] = ...,
-        copy: bool = ...,
     ) -> met_module.MetDataset: ...
 
     @overload
@@ -1831,7 +1854,6 @@ class GeoVectorDataset(VectorDataset):
         latitude_buffer: tuple[float, float] = ...,
         level_buffer: tuple[float, float] = ...,
         time_buffer: tuple[np.timedelta64, np.timedelta64] = ...,
-        copy: bool = ...,
     ) -> met_module.MetDataArray: ...
 
     def downselect_met(
@@ -1845,10 +1867,13 @@ class GeoVectorDataset(VectorDataset):
             np.timedelta64(0, "h"),
             np.timedelta64(0, "h"),
         ),
-        copy: bool = True,
     ) -> met_module.MetDataType:
         """Downselect ``met`` to encompass a spatiotemporal region of the data.
 
+        .. versionchanged:: 0.54.5
+
+            Returned object is no longer copied.
+
         Parameters
         ----------
         met : MetDataset | MetDataArray
@@ -1873,8 +1898,6 @@ class GeoVectorDataset(VectorDataset):
             and ``time_buffer[1]`` on the high side.
             Units must be the same as class coordinates.
             Defaults to ``(np.timedelta64(0, "h"), np.timedelta64(0, "h"))``.
-        copy : bool
-            If returned object is a copy or view of the original. True by default.
 
         Returns
         -------
@@ -1915,7 +1938,7 @@ class GeoVectorDataset(VectorDataset):
             level=level_slice,
             time=time_slice,
         )
-        return type(met)(data, copy=copy)
+        return type(met)._from_fastpath(data)
 
     # ------------
     # I / O

pycontrails/datalib/_met_utils/metsource.py

@@ -265,7 +265,7 @@ def _find_match(
 
     # list of MetVariable options
     # here we extract the first MetVariable in var that is supported
-    elif isinstance(var, list | tuple):
+    if isinstance(var, list | tuple):
         for v in var:
             # sanity check since we don't support other types as lists
             if not isinstance(v, MetVariable):

pycontrails/datalib/ecmwf/era5.py

@@ -88,9 +88,8 @@ class ERA5(ECMWFAPI):
         If None, cache is turned off.
     url : str | None
         Override the default `cdsapi <https://github.com/ecmwf/cdsapi>`_ url.
-        As of August 2024, the url for the `CDS-Beta <https://cds-beta.climate.copernicus.eu>`_
-        is "https://cds-beta.climate.copernicus.eu/api", and the url for the legacy server is
-        "https://cds.climate.copernicus.eu/api/v2". If None, the url is set
+        As of January 2025, the url for the `CDS Server <https://cds.climate.copernicus.eu>`_
+        is "https://cds.climate.copernicus.eu/api". If None, the url is set
         by the ``CDSAPI_URL`` environment variable. If this is not defined, the
         ``cdsapi`` package will determine the url.
     key : str | None
@@ -539,12 +538,12 @@ class ERA5(ECMWFAPI):
             LOG.debug("Input dataset processed with pycontrails > 0.29")
             return ds
 
-        # For "reanalysis-era5-single-levels"
-        # then the netcdf file does not contain the dimension "level"
+        # For "reanalysis-era5-single-levels",
+        # the netcdf file does not contain the dimension "level"
         if self.is_single_level:
             ds = ds.expand_dims(level=self.pressure_levels)
 
-        # New CDS-Beta gives "valid_time" instead of "time"
+        # New CDS (Aug 2024) gives "valid_time" instead of "time"
         # and "pressure_level" instead of "level"
         if "valid_time" in ds:
             ds = ds.rename(valid_time="time")

pycontrails/datalib/ecmwf/era5_model_level.py

@@ -119,9 +119,8 @@ class ERA5ModelLevel(ECMWFAPI):
         By default, False.
     url : str | None
         Override the default `cdsapi <https://github.com/ecmwf/cdsapi>`_ url.
-        As of August 2024, the url for the `CDS-Beta <https://cds-beta.climate.copernicus.eu>`_
-        is "https://cds-beta.climate.copernicus.eu/api", and the url for the legacy server is
-        "https://cds.climate.copernicus.eu/api/v2". If None, the url is set
+        As of January 2025, the url for the `CDS Server <https://cds.climate.copernicus.eu>`_
+        is "https://cds.climate.copernicus.eu/api". If None, the url is set
         by the ``CDSAPI_URL`` environment variable. If this is not defined, the
         ``cdsapi`` package will determine the url.
     key : str | None
@@ -465,13 +464,13 @@ class ERA5ModelLevel(ECMWFAPI):
             ds_ml = xr.open_dataset(ml_target)
             lnsp = xr.open_dataarray(lnsp_target)
 
-            # New CDS-Beta gives "valid_time" instead of "time"
+            # New CDS (Aug 2024) gives "valid_time" instead of "time"
             if "valid_time" in ds_ml:
                 ds_ml = ds_ml.rename(valid_time="time")
             if "valid_time" in lnsp.dims:
                 lnsp = lnsp.rename(valid_time="time")
 
-            # The legacy CDS gives "level" instead of "model_level"
+            # Legacy CDS (prior to Aug 2024) gives "level" instead of "model_level"
             if "level" in ds_ml.dims:
                 ds_ml = ds_ml.rename(level="model_level")
 

pycontrails/datalib/ecmwf/ifs.py

@@ -247,9 +247,7 @@ class IFS(metsource.MetDataSource):
         ds_fl = ds_fl.drop_vars(names=["hyai", "hybi", "hyam", "hybm"])
 
         # merge all datasets using the "ds_fl" dimensions as the join keys
-        ds = xr.merge([ds_fl, ds_full, ds_surface, ds_rad], join="left")  # order matters!
-
-        return ds
+        return xr.merge([ds_fl, ds_full, ds_surface, ds_rad], join="left")  # order matters!
 
     def _calc_geopotential(self, ds: xr.Dataset) -> xr.DataArray:
         warnings.warn(

pycontrails/datalib/gfs/gfs.py

@@ -570,9 +570,7 @@ class GFSForecast(metsource.MetDataSource):
         ds = ds.expand_dims("time")
 
         # drop step/number
-        ds = ds.drop_vars(["step", "nominalTop", "surface"], errors="ignore")
-
-        return ds
+        return ds.drop_vars(["step", "nominalTop", "surface"], errors="ignore")
 
     def _process_dataset(self, ds: xr.Dataset, **kwargs: Any) -> met.MetDataset:
         """Process the :class:`xr.Dataset` opened from cache or local files.

pycontrails/models/apcemm/apcemm.py

@@ -474,7 +474,7 @@ class APCEMM(models.Model):
             for coord in ("longitude", "latitude", "level")
         }
         buffers["time_buffer"] = (0, self.params["max_age"] + self.params["dt_lagrangian"])
-        met = self.source.downselect_met(self.met, **buffers, copy=False)
+        met = self.source.downselect_met(self.met, **buffers)
         model = DryAdvection(
             met=met,
             dt_integration=self.params["dt_lagrangian"],
@@ -816,7 +816,7 @@ class APCEMM(models.Model):
         # Ensure required met data is present.
         # No buffers needed for interpolation!
         vars = ap_model.met_variables + ap_model.optional_met_variables + emissions.met_variables
-        met = self.source.downselect_met(self.met, copy=False)
+        met = self.source.downselect_met(self.met)
         met.ensure_vars(vars)
         met.standardize_variables(vars)
         for var in vars:

pycontrails/models/apcemm/utils.py

@@ -214,7 +214,7 @@ def generate_apcemm_input_met(
     )
 
     # Downselect met before interpolation
-    met = vector.downselect_met(met, copy=False)
+    met = vector.downselect_met(met)
 
     # Interpolate meteorology data onto vector
     scale_humidity = humidity_scaling is not None and "specific_humidity" not in vector