pycontrails 0.54.6__tar.gz → 0.54.7__tar.gz

{pycontrails-0.54.6 → pycontrails-0.54.7}/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## v0.54.7
+
+### Features
+
+- Add helper `classmethods` to `Model`, `Cocip`, and `CocipGrid` for generating lists of required variables from specific data sources.
+- Add a `ValidateTrajectoryHandler` to the `spire` module to validate spire ADS-B data. This work is experimental and will be improved in future releases.
+- Update Unterstrasser (2016)'s parameterised model of the contrail ice crystal survival fraction to the latest version (Lottermoser & Unterstrasser, 2025). This update:
+  - improves the goodness of fit between the parameterised model and LES, and
+  - expands the parameter space for application to very low and very high nvPM inputs, different fuel types (where the EI H2Os are different), and higher ambient temperatures (up to 235 K) to accommodate for contrails formed by liquid hydrogen aircraft.
+
+### Breaking changes
+
+- The `MetDataset.standardize_variables` method now returns a new `MetDataset` rather than modifying the existing dataset in place. To retain the previous behavior, use `MetDataset.standardize_variables(..., inplace=True)`.
+
+### Fixes
+
+- Change naming convention for eastward and northward wind fields in `AircraftPerformance` models for consistency with the `Cocip` and `DryAdvection` models. Fields on the `source` are now named `u_wind` and `v_wind` instead of `eastward_wind` and `northward_wind`. Under some paths of computation, this avoids a redundant interpolation.
+- Fix the `AircraftPerformance.ensure_true_airspeed_on_source` method in the case when the `met` attr is None and the `fill_with_groundspeed` parameter is enabled.
+
+### Internals
+
+- Make `pycontrails` compatible with `pandas 2.0` and `pandas 2.1`.
+- Avoid auto-promotion of float32 to float64 within the `Emissions` model run-time.
+- Add convenience `VectorDataset.get_constant` method.
+
 ## v0.54.6
 
 ### Features

{pycontrails-0.54.6 → pycontrails-0.54.7}/NOTICE

@@ -1,4 +1,4 @@
-Copyright (c) 2021-present Breakthrough Energy
+Copyright (c) 2021-present Contrails.org and the Breakthrough Energy Foundation
 
 
 Attribution

{pycontrails-0.54.6/pycontrails.egg-info → pycontrails-0.54.7}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.2
 Name: pycontrails
-Version: 0.54.6
+Version: 0.54.7
 Summary: Python library for modeling aviation climate impacts
-Author-email: Breakthrough Energy <py@contrails.org>
+Author-email: "Contrails.org" <py@contrails.org>
 License: Apache-2.0
 Project-URL: Changelog, https://py.contrails.org/changelog.html
 Project-URL: Documentation, https://py.contrails.org
@@ -29,7 +29,7 @@ License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: dask>=2022.3
 Requires-Dist: numpy>=1.22
-Requires-Dist: pandas>=2.2
+Requires-Dist: pandas>=2.0
 Requires-Dist: scipy>=1.10
 Requires-Dist: typing-extensions>=4.5; python_version < "3.12"
 Requires-Dist: xarray>=2022.3

{pycontrails-0.54.6 → pycontrails-0.54.7}/RELEASE.md

@@ -11,7 +11,7 @@
    Double check that the release tag is consistent and consecutive with
    the previous release tag following [PEP 440](https://peps.python.org/pep-0440/#version-scheme).
    This often but not always agrees with [Semantic Versioning](https://semver.org/).
-1. Copy the CHANGELOG content for the release into the *Description*.
+1. Copy the [CHANGELOG](https://raw.githubusercontent.com/contrailcirrus/pycontrails/refs/heads/main/CHANGELOG.md) content for the release into the *Description*.
 1. Publish the new release.
    This will create a tag on `main` and trigger the [Release Action](https://github.com/contrailcirrus/pycontrails/actions/workflows/release.yaml).
 1. Confirm that the release is successfully deployed to [PyPI](https://pypi.org/project/pycontrails/).

{pycontrails-0.54.6 → pycontrails-0.54.7}/docs/conf.py

@@ -15,9 +15,11 @@ import pycontrails
 # -- Project information -----------------------------------------------------
 
 project = "pycontrails"
-copyright = f"2021-{datetime.datetime.now().year}, Breakthrough Energy"
+copyright = (
+    f"2021-{datetime.datetime.now().year}, Contrails.org and the Breakthrough Energy Foundation"
+)
 
-author = "Breakthrough Energy"
+author = "Contrails.org"
 version = pycontrails.__version__
 release = pycontrails.__version__
 

{pycontrails-0.54.6 → pycontrails-0.54.7}/pycontrails/__init__.py

@@ -1,7 +1,7 @@
 """
 ``pycontrails`` public API.
 
-Copyright 2021-present Breakthrough Energy
+Copyright 2021-present Contrails.org and the Breakthrough Energy Foundation
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

{pycontrails-0.54.6 → pycontrails-0.54.7}/pycontrails/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.54.6'
-__version_tuple__ = version_tuple = (0, 54, 6)
+__version__ = version = '0.54.7'
+__version_tuple__ = version_tuple = (0, 54, 7)

{pycontrails-0.54.6 → pycontrails-0.54.7}/pycontrails/core/aircraft_performance.py

@@ -71,6 +71,8 @@ class AircraftPerformanceParams(ModelParams, CommonAircraftPerformanceParams):
     #: 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.
+    #: In the case that ``met`` is not provided, any missing values are
+    #: filled with zero wind.
     fill_low_altitude_with_zero_wind: bool = False
 
 
@@ -509,7 +511,8 @@ class AircraftPerformance(Model):
             tas[cond] = self.source.segment_groundspeed()[cond]
             return tas
 
-        wind_available = ("eastward_wind" in self.source and "northward_wind" in self.source) or (
+        # Use current cocip convention: eastward_wind on met, u_wind on source
+        wind_available = ("u_wind" in self.source and "v_wind" in self.source) or (
             self.met is not None and "eastward_wind" in self.met and "northward_wind" in self.met
         )
 
@@ -526,12 +529,16 @@ class AircraftPerformance(Model):
             )
             raise ValueError(msg)
 
-        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", "u_wind", **self.interp_kwargs)
+        v = interpolate_met(self.met, self.source, "northward_wind", "v_wind", **self.interp_kwargs)
 
         if fill_with_groundspeed:
-            met_level_max = self.met.data["level"][-1].item()  # type: ignore[union-attr]
-            cond = self.source.level > met_level_max
+            if self.met is None:
+                cond = np.isnan(u) & np.isnan(v)
+            else:
+                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)
@@ -657,28 +664,3 @@ def _fill_low_altitude_with_isa_temperature(vector: GeoVectorDataset, met_level_
 
     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-0.54.6 → pycontrails-0.54.7}/pycontrails/core/airports.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import functools
+
 import numpy as np
 import pandas as pd
 
@@ -35,6 +37,7 @@ def _download_ourairports_csv() -> pd.DataFrame:
     )
 
 
+@functools.cache
 def global_airport_database(
     cachestore: cache.CacheStore | None = None, update_cache: bool = False
 ) -> pd.DataFrame:
@@ -91,7 +94,7 @@ def global_airport_database(
     airports = airports.rename(
         columns={"latitude_deg": "latitude", "longitude_deg": "longitude", "gps_code": "icao_code"},
     )
-    airports.fillna({"elevation_ft": 0}, inplace=True)
+    airports.fillna({"elevation_ft": 0.0}, inplace=True)
 
     # Keep specific airport types used by commercial aviation
     subset = ("large_airport", "medium_airport", "small_airport", "heliport")

{pycontrails-0.54.6 → pycontrails-0.54.7}/pycontrails/core/flight.py

@@ -1388,7 +1388,7 @@ class Flight(GeoVectorDataset):
 
         jump_indices = _antimeridian_index(pd.Series(self["longitude"]))
 
-        def _group_to_feature(group: pd.DataFrame) -> dict[str, str | dict[str, Any]]:
+        def _group_to_feature(name: str, group: pd.DataFrame) -> dict[str, str | dict[str, Any]]:
             # assigns a different value to each group of consecutive indices
             subgrouping = group.index.to_series().diff().ne(1).cumsum()
 
@@ -1405,7 +1405,7 @@ class Flight(GeoVectorDataset):
             geometry = {"type": "MultiLineString", "coordinates": multi_ls}
 
             # adding in static properties
-            properties: dict[str, Any] = {key: group.name} if key is not None else {}
+            properties: dict[str, Any] = {key: name} if key is not None else {}
             properties.update(self.constants)
             return {"type": "Feature", "geometry": geometry, "properties": properties}
 
@@ -1415,11 +1415,11 @@ class Flight(GeoVectorDataset):
             # create a single group containing all rows of dataframe
             groups = self.dataframe.groupby(lambda _: 0)
 
-        features = groups.apply(_group_to_feature, include_groups=False).values.tolist()
+        features = [_group_to_feature(*name_group) for name_group in groups]
         return {"type": "FeatureCollection", "features": features}
 
     def to_traffic(self) -> traffic.core.Flight:
-        """Convert to :class:`traffic.core.Flight`instance.
+        """Convert to :class:`traffic.core.Flight` instance.
 
         Returns
         -------

{pycontrails-0.54.6 → pycontrails-0.54.7}/pycontrails/core/met.py

@@ -150,11 +150,8 @@ class MetBase(ABC, Generic[XArrayType]):
         """
         longitude = self.indexes["longitude"].to_numpy()
         if longitude.dtype != COORD_DTYPE:
-            raise ValueError(
-                "Longitude values must be of type float64. "
-                "Instantiate with 'copy=True' to convert to float64. "
-                "Instantiate with 'validate=False' to skip validation."
-            )
+            msg = f"Longitude values must have dtype {COORD_DTYPE}. Instantiate with 'copy=True'."
+            raise ValueError(msg)
 
         if self.is_wrapped:
             # Relax verification if the longitude has already been processed and wrapped
@@ -194,11 +191,8 @@ class MetBase(ABC, Generic[XArrayType]):
         """
         latitude = self.indexes["latitude"].to_numpy()
         if latitude.dtype != COORD_DTYPE:
-            raise ValueError(
-                "Latitude values must be of type float64. "
-                "Instantiate with 'copy=True' to convert to float64. "
-                "Instantiate with 'validate=False' to skip validation."
-            )
+            msg = f"Latitude values must have dtype {COORD_DTYPE}. Instantiate with 'copy=True'."
+            raise ValueError(msg)
 
         if latitude[0] < -90.0:
             raise ValueError(
@@ -233,8 +227,8 @@ class MetBase(ABC, Generic[XArrayType]):
             if da.dims != self.dim_order:
                 if key is not None:
                     msg = (
-                        f"Data dimension not transposed on variable '{key}'. Instantiate with"
-                        " 'copy=True'."
+                        f"Data dimension not transposed on variable '{key}'. "
+                        "Instantiate with 'copy=True'."
                     )
                 else:
                     msg = "Data dimension not transposed. Instantiate with 'copy=True'."
@@ -258,11 +252,8 @@ class MetBase(ABC, Generic[XArrayType]):
         self._validate_latitude()
         self._validate_transpose()
         if self.data["level"].dtype != COORD_DTYPE:
-            raise ValueError(
-                "Level values must be of type float64. "
-                "Instantiate with 'copy=True' to convert to float64. "
-                "Instantiate with 'validate=False' to skip validation."
-            )
+            msg = f"Level values must have dtype {COORD_DTYPE}. Instantiate with 'copy=True'."
+            raise ValueError(msg)
 
     def _preprocess_dims(self, wrap_longitude: bool) -> None:
         """Confirm DataArray or Dataset include required dimension in a consistent format.
@@ -435,7 +426,7 @@ class MetBase(ABC, Generic[XArrayType]):
         Assumes the longitude dimension is sorted (this is established by the
         :class:`MetDataset` or :class:`MetDataArray` constructor).
 
-        .. versionchanged 0.26.0::
+        .. versionchanged:: 0.26.0
 
             The previous implementation checked for the minimum and maximum longitude
             dimension values to be duplicated. The current implementation only checks for
@@ -492,7 +483,7 @@ class MetBase(ABC, Generic[XArrayType]):
 
         Does not yet save in parallel.
 
-        .. versionchanged::0.34.1
+        .. versionchanged:: 0.34.1
 
             If :attr:`cachestore` is None, this method assigns it
             to new :class:`DiskCacheStore`.
@@ -1178,19 +1169,45 @@ class MetDataset(MetBase):
         }
         return self._get_pycontrails_attr_template("product", supported, examples)
 
-    def standardize_variables(self, variables: Iterable[MetVariable]) -> None:
-        """Standardize variables **in-place**.
+    @overload
+    def standardize_variables(
+        self, variables: Iterable[MetVariable], inplace: Literal[False] = ...
+    ) -> Self: ...
+
+    @overload
+    def standardize_variables(
+        self, variables: Iterable[MetVariable], inplace: Literal[True]
+    ) -> None: ...
+
+    def standardize_variables(
+        self, variables: Iterable[MetVariable], inplace: bool = False
+    ) -> Self | None:
+        """Standardize variable names.
+
+        .. versionchanged:: 0.54.7
+
+            By default, this method returns a new :class:`MetDataset` instead
+            of renaming in place. To retain the old behavior, set ``inplace=True``.
 
         Parameters
         ----------
         variables : Iterable[MetVariable]
             Data source variables
+        inplace : bool, optional
+            If True, rename variables in place. Otherwise, return a new
+            :class:`MetDataset` with renamed variables.
 
         See Also
         --------
         :func:`standardize_variables`
         """
-        standardize_variables(self, variables)
+        data_renamed = standardize_variables(self.data, variables)
+
+        if inplace:
+            self.data = data_renamed
+            return None
+
+        return type(self)._from_fastpath(data_renamed, cachestore=self.cachestore)
 
     @classmethod
     def from_coords(
@@ -2642,7 +2659,7 @@ def downselect(data: XArrayType, bbox: tuple[float, ...]) -> XArrayType:
     return data.where(cond, drop=True)
 
 
-def standardize_variables(ds: DatasetType, variables: Iterable[MetVariable]) -> DatasetType:
+def standardize_variables(ds: xr.Dataset, variables: Iterable[MetVariable]) -> xr.Dataset:
     """Rename all variables in dataset from short name to standard name.
 
     This function does not change any variables in ``ds`` that are not found in ``variables``.
@@ -2652,8 +2669,7 @@ def standardize_variables(ds: DatasetType, variables: Iterable[MetVariable]) ->
     Parameters
     ----------
     ds : DatasetType
-        An :class:`xr.Dataset` or :class:`MetDataset`. When a :class:`MetDataset` is
-        passed, the underlying :class:`xr.Dataset` is modified in place.
+        An :class:`xr.Dataset`.
     variables : Iterable[MetVariable]
         Data source variables
 
@@ -2662,14 +2678,6 @@ def standardize_variables(ds: DatasetType, variables: Iterable[MetVariable]) ->
     DatasetType
         Dataset with variables renamed to standard names
     """
-    if isinstance(ds, xr.Dataset):
-        return _standardize_variables(ds, variables)
-
-    ds.data = _standardize_variables(ds.data, variables)
-    return ds
-
-
-def _standardize_variables(ds: xr.Dataset, variables: Iterable[MetVariable]) -> xr.Dataset:
     variables_dict: dict[Hashable, str] = {v.short_name: v.standard_name for v in variables}
     name_dict = {var: variables_dict[var] for var in ds.data_vars if var in variables_dict}
     return ds.rename(name_dict)

{pycontrails-0.54.6 → pycontrails-0.54.7}/pycontrails/core/met_var.py

@@ -367,3 +367,21 @@ TOAOutgoingLongwaveFlux = MetVariable(
         '"flux" implies per unit area, called "flux density" in physics.'
     ),
 )
+
+PRESSURE_LEVEL_VARIABLES = [
+    AirTemperature,
+    SpecificHumidity,
+    RelativeHumidity,
+    Geopotential,
+    GeopotentialHeight,
+    EastwardWind,
+    NorthwardWind,
+    VerticalVelocity,
+    MassFractionOfCloudLiquidWaterInAir,
+    MassFractionOfCloudIceInAir,
+    CloudAreaFractionInAtmosphereLayer,
+]
+
+SINGLE_LEVEL_VARIABLES = [SurfacePressure, TOANetDownwardShortwaveFlux, TOAOutgoingLongwaveFlux]
+
+MET_VARIABLES = PRESSURE_LEVEL_VARIABLES + SINGLE_LEVEL_VARIABLES

{pycontrails-0.54.6 → pycontrails-0.54.7}/pycontrails/core/models.py

@@ -22,8 +22,10 @@ import xarray as xr
 from pycontrails.core.fleet import Fleet
 from pycontrails.core.flight import Flight
 from pycontrails.core.met import MetDataArray, MetDataset, MetVariable, originates_from_ecmwf
-from pycontrails.core.met_var import SpecificHumidity
+from pycontrails.core.met_var import MET_VARIABLES, SpecificHumidity
 from pycontrails.core.vector import GeoVectorDataset
+from pycontrails.datalib.ecmwf import ECMWF_VARIABLES
+from pycontrails.datalib.gfs import GFS_VARIABLES
 from pycontrails.utils.json import NumpyEncoder
 from pycontrails.utils.types import type_guard
 
@@ -179,8 +181,10 @@ class Model(ABC):
 
     #: Required meteorology pressure level variables.
     #: Each element in the list is a :class:`MetVariable` or a ``tuple[MetVariable]``.
-    #: If element is a ``tuple[MetVariable]``, the variable depends on the data source.
-    #: Only one variable in the tuple is required.
+    #: If element is a ``tuple[MetVariable]``, the variable depends on the data source
+    #: and the tuple must include entries for a model-agnostic variable,
+    #: an ECMWF-specific variable, and a GFS-specific variable.
+    #: Only one of the three variable in the tuple is required for model evaluation.
     met_variables: tuple[MetVariable | tuple[MetVariable, ...], ...]
 
     #: Set of required parameters if processing already complete on ``met`` input.
@@ -276,6 +280,42 @@ class Model(ABC):
 
         return hashlib.sha1(bytes(_hash, "utf-8")).hexdigest()
 
+    @classmethod
+    def generic_met_variables(cls) -> tuple[MetVariable, ...]:
+        """Return a model-agnostic list of required meteorology variables.
+
+        Returns
+        -------
+        tuple[MetVariable]
+            List of model-agnostic variants of required variables
+        """
+        available = set(MET_VARIABLES)
+        return tuple(_find_match(required, available) for required in cls.met_variables)
+
+    @classmethod
+    def ecmwf_met_variables(cls) -> tuple[MetVariable, ...]:
+        """Return an ECMWF-specific list of required meteorology variables.
+
+        Returns
+        -------
+        tuple[MetVariable]
+            List of ECMWF-specific variants of required variables
+        """
+        available = set(ECMWF_VARIABLES)
+        return tuple(_find_match(required, available) for required in cls.met_variables)
+
+    @classmethod
+    def gfs_met_variables(cls) -> tuple[MetVariable, ...]:
+        """Return a GFS-specific list of required meteorology variables.
+
+        Returns
+        -------
+        tuple[MetVariable]
+            List of GFS-specific variants of required variables
+        """
+        available = set(GFS_VARIABLES)
+        return tuple(_find_match(required, available) for required in cls.met_variables)
+
     def _verify_met(self) -> None:
         """Verify integrity of :attr:`met`.
 
@@ -805,6 +845,42 @@ def _interp_grid_to_grid(
     raise NotImplementedError(msg)
 
 
+def _find_match(
+    required: MetVariable | Sequence[MetVariable], available: set[MetVariable]
+) -> MetVariable:
+    """Find match for required met variable in list of data-source-specific met variables.
+
+    Parameters
+    ----------
+    required : MetVariable | Sequence[MetVariable]
+        Required met variable
+
+    available : Sequence[MetVariable]
+        Collection of data-source-specific met variables
+
+    Returns
+    -------
+    MetVariable
+        Match for required met variable in collection of data-source-specific met variables
+
+    Raises
+    ------
+    KeyError
+        Raised if not match is found
+    """
+    if isinstance(required, MetVariable):
+        return required
+
+    for var in required:
+        if var in available:
+            return var
+
+    required_keys = [v.standard_name for v in required]
+    available_keys = [v.standard_name for v in available]
+    msg = f"None of {required_keys} match variable in {available_keys}"
+    raise KeyError(msg)
+
+
 def _raise_missing_met_var(var: MetVariable | Sequence[MetVariable]) -> NoReturn:
     """Raise KeyError on missing met variable.