pycontrails 0.54.8__tar.gz → 0.54.10__tar.gz

{pycontrails-0.54.8 → pycontrails-0.54.10}/.github/workflows/release.yaml

@@ -145,3 +145,21 @@ jobs:
 
       - name: Publish distribution 📦 to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+  run-pycontrails-bada-tests:
+    # Run the test workflow in pycontrails-bada after publishing to PyPI
+    if: ${{ github.event_name == 'release'}}
+    needs:
+      - publish-to-pypi
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger pycontrails-bada tests
+        run: |
+          gh api \
+          --method POST \
+          -H "Accept: application/vnd.github.v3+json" \
+          /repos/contrailcirrus/pycontrails-bada/dispatches \
+          -f event_type="pycontrails-release"
+        env:
+          GH_TOKEN: ${{ secrets.GH_ROBOT_USER_PAT }}

{pycontrails-0.54.8 → pycontrails-0.54.10}/.github/workflows/test.yaml

@@ -70,8 +70,8 @@ jobs:
       - name: Set up Cloud SDK
         uses: google-github-actions/setup-gcloud@v2
 
-      # download BADA files for testing
-      - name: BADA files
+      - name: Download BADA files
+        timeout-minutes: 5  # `gcloud storage cp` occasionally hangs on windows
         run: |
           mkdir -p ${{ env.BADA_CACHE_DIR }}
           gcloud storage cp -r gs://contrails-301217-bada/bada/bada3 ${{ env.BADA_CACHE_DIR }}

{pycontrails-0.54.8 → pycontrails-0.54.10}/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.54.10
+
+### Features
+
+- Output from the `DryAdvection` model will include a `flight_id` column when run with a `Flight` or a `Fleet`.
+
+### Fixes
+
+- GOES data download for GOES-East now supports the GOES-16 -> GOES-19 transition. The default GCS bucket is automatically selected based on the requested date (using 2025-04-04 as the cutoff). For pre-transition data, this change is backwards compatible with previous versions of pycontrails.
+- Pass the `GOES.fs` instance to the `gcs_goes_path` function from the `GOES.gcs_goes_path` method to avoid repeated GCS file system client instantiation.
+
+### Internals
+
+- Fix errors in "See Also" sections of `Model` docstrings.
+
+## 0.54.9
+
+### Features
+
+- Include new `goes.correct_parallax` function in the `GOES` datalib to correct for parallax artifacts in GOES imagery. This function can be used to better superimpose flight and contrail data over GOES imagery.
+
+### Breaking changes
+
+- Air temperature is now an optional met variable in `PSFlight`. Code that uses `PSFlight.met_variables` may need to be updated.
+- The `ensure_true_airspeed_on_source` method of the `AircraftPerformance` class now operates fully in-place and no longer returns a value. Code that relies on a return value may need to be updated.
+- The `PSFlight.eval_flight` method now retrieves all inputs to performance calculations from the `Flight` parameter rather than the `PSFlight` model source. Code may need to be updated if constants for `aircraft_mass`, `thrust`, `engine_efficiency`, or `fuel_flow` were stored as attributes in a `Fleet`, as these attributes are lost when a `Fleet` is converted to a `Flight` list prior to calling `eval_flight`.
+
+### Internals
+
+- Define `default_parameters`, `met_variables`, and `optional_met_variables` for the `AircraftPerformance` abstract base class.
+- Remove the definitions of `met_variables` and `optional_met_variables` from `PSFlight`. These are now inherited from `AircraftPerformance`.
+- Retrieve aircraft mass, thrust, engine efficiency, and fuel flow from `Flight` parameter rather than model source in `PSFlight.eval_flight`.
+- Automatically run the [pycontrails-bada test](https://github.com/contrailcirrus/pycontrails-bada/actions/workflows/test.yml) workflow after publishing pycontrails release to PyPI.
+
 ## 0.54.8
 
 ### Features

{pycontrails-0.54.8/pycontrails.egg-info → pycontrails-0.54.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycontrails
-Version: 0.54.8
+Version: 0.54.10
 Summary: Python library for modeling aviation climate impacts
 Author-email: "Contrails.org" <py@contrails.org>
 License: Apache-2.0

{pycontrails-0.54.8 → pycontrails-0.54.10}/pycontrails/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.54.8'
-__version_tuple__ = version_tuple = (0, 54, 8)
+__version__ = version = '0.54.10'
+__version_tuple__ = version_tuple = (0, 54, 10)

{pycontrails-0.54.8 → pycontrails-0.54.10}/pycontrails/core/aircraft_performance.py

@@ -4,15 +4,9 @@ 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
 
@@ -20,6 +14,7 @@ from pycontrails.core import flight, fuel
 from pycontrails.core.fleet import Fleet
 from pycontrails.core.flight import Flight
 from pycontrails.core.met import MetDataset
+from pycontrails.core.met_var import AirTemperature, EastwardWind, MetVariable, NorthwardWind
 from pycontrails.core.models import Model, ModelParams, interpolate_met
 from pycontrails.core.vector import GeoVectorDataset
 from pycontrails.physics import jet
@@ -97,6 +92,9 @@ class AircraftPerformance(Model):
     """
 
     source: Flight
+    met_variables: tuple[MetVariable, ...] = ()
+    optional_met_variables: tuple[MetVariable, ...] = (AirTemperature, EastwardWind, NorthwardWind)
+    default_params = AircraftPerformanceParams
 
     @overload
     def eval(self, source: Fleet, **params: Any) -> Fleet: ...
@@ -129,7 +127,8 @@ class AircraftPerformance(Model):
         self.set_source_met()
         self._cleanup_indices()
 
-        # Calculate true airspeed if not included on source
+        # Calculate temperature and true airspeed if not included on source
+        self.ensure_air_temperature_on_source()
         self.ensure_true_airspeed_on_source()
 
         if isinstance(self.source, Fleet):
@@ -162,23 +161,6 @@ class AircraftPerformance(Model):
         - ``total_fuel_burn``: total fuel burn, [:math:`kg`]
         """
 
-    @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):
-            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,
         *,
@@ -491,25 +473,57 @@ class AircraftPerformance(Model):
             Derived performance metrics at each waypoint.
         """
 
-    def ensure_true_airspeed_on_source(self) -> npt.NDArray[np.floating]:
+    def ensure_air_temperature_on_source(self) -> None:
+        """Add ``air_temperature`` field to :attr:`source` data if not already present.
+
+        This function operates in-place. If ``air_temperature`` is not already present
+        on :attr:`source`, it is calculated by interpolation from met data.
+        """
+        fill_with_isa = self.params["fill_low_altitude_with_isa_temperature"]
+
+        if "air_temperature" in self.source:
+            if not fill_with_isa:
+                return
+            _fill_low_altitude_with_isa_temperature(self.source, 0.0)
+            return
+
+        temp_available = self.met is not None and "air_temperature" in self.met
+
+        if not temp_available:
+            if fill_with_isa:
+                self.source["air_temperature"] = self.source.T_isa()
+                return
+            msg = (
+                "Cannot compute air temperature without providing met data that includes an "
+                "'air_temperature' variable. Either include met data with 'air_temperature' "
+                "in the model constructor, define 'air_temperature' data on the flight, or set "
+                "'fill_low_altitude_with_isa_temperature' to True."
+            )
+            raise ValueError(msg)
+
+        interpolate_met(self.met, self.source, "air_temperature", **self.interp_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 ensure_true_airspeed_on_source(self) -> None:
         """Add ``true_airspeed`` field to :attr:`source` data if not already present.
 
-        Returns
-        -------
-        npt.NDArray[np.floating]
-            True airspeed, [:math:`m s^{-1}`]. If ``true_airspeed`` is already present
-            on :attr:`source`, this is returned directly. Otherwise, it is calculated
-            using :meth:`Flight.segment_true_airspeed`.
+        This function operates in-place. If ``true_airspeed`` is not already present
+        on :attr:`source`, 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
+                return
             cond = np.isnan(tas)
             tas[cond] = self.source.segment_groundspeed()[cond]
-            return tas
+            return
 
         # 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 (
@@ -520,7 +534,7 @@ class AircraftPerformance(Model):
             if fill_with_groundspeed:
                 tas = self.source.segment_groundspeed()
                 self.source["true_airspeed"] = tas
-                return tas
+                return
             msg = (
                 "Cannot compute 'true_airspeed' without 'eastward_wind' and 'northward_wind' "
                 "met data. Either include met data in the model constructor, define "
@@ -545,7 +559,6 @@ class AircraftPerformance(Model):
 
         out = self.source.segment_true_airspeed(u, v)
         self.source["true_airspeed"] = out
-        return out
 
 
 @dataclasses.dataclass

{pycontrails-0.54.8 → pycontrails-0.54.10}/pycontrails/core/models.py

@@ -543,7 +543,7 @@ class Model(ABC):
 
         See Also
         --------
-        - :meth:`eval`
+        eval
         """
         self.source = self._get_source(source)
 
@@ -706,17 +706,20 @@ class Model(ABC):
     # https://github.com/python/cpython/blob/618b7a8260bb40290d6551f24885931077309590/Lib/collections/__init__.py#L231
     __marker = object()
 
-    def get_source_param(self, key: str, default: Any = __marker, *, set_attr: bool = True) -> Any:
-        """Get source data with default set by parameter key.
+    def get_data_param(
+        self, other: SourceType, key: str, default: Any = __marker, *, set_attr: bool = True
+    ) -> Any:
+        """Get data from other source-compatible object with default set by model parameter key.
 
         Retrieves data with the following hierarchy:
 
-        1. :attr:`source.data[key]`. Returns ``np.ndarray | xr.DataArray``.
-        2. :attr:`source.attrs[key]`
+        1. :attr:`other.data[key]`. Returns ``np.ndarray | xr.DataArray``.
+        2. :attr:`other.attrs[key]`
         3. :attr:`params[key]`
         4. ``default``
 
-        In case 3., the value of :attr:`params[key]` is attached to :attr:`source.attrs[key]`.
+        In case 3., the value of :attr:`params[key]` is attached to :attr:`other.attrs[key]`
+        unless ``set_attr`` is set to False.
 
         Parameters
         ----------
@@ -731,31 +734,33 @@ class Model(ABC):
         Returns
         -------
         Any
-            Value(s) found for key in source data, source attrs, or model params
+            Value(s) found for key in ``other`` data, ``other`` attrs, or model params
 
         Raises
         ------
         KeyError
             Raises KeyError if key is not found in any location and ``default`` is not provided.
 
+
         See Also
         --------
-        - GeoVectorDataset.get_data_or_attr
+        get_source_param
+        pycontrails.core.vector.GeoVectorDataset.get_data_or_attr
         """
         marker = self.__marker
 
-        out = self.source.data.get(key, marker)
+        out = other.data.get(key, marker)
         if out is not marker:
             return out
 
-        out = self.source.attrs.get(key, marker)
+        out = other.attrs.get(key, marker)
         if out is not marker:
             return out
 
         out = self.params.get(key, marker)
         if out is not marker:
             if set_attr:
-                self.source.attrs[key] = out
+                other.attrs[key] = out
 
             return out
 
@@ -765,6 +770,46 @@ class Model(ABC):
         msg = f"Key '{key}' not found in source data, attrs, or model params"
         raise KeyError(msg)
 
+    def get_source_param(self, key: str, default: Any = __marker, *, set_attr: bool = True) -> Any:
+        """Get source data with default set by parameter key.
+
+        Retrieves data with the following hierarchy:
+
+        1. :attr:`source.data[key]`. Returns ``np.ndarray | xr.DataArray``.
+        2. :attr:`source.attrs[key]`
+        3. :attr:`params[key]`
+        4. ``default``
+
+        In case 3., the value of :attr:`params[key]` is attached to :attr:`source.attrs[key]`
+        unless ``set_attr`` is set to False.
+
+        Parameters
+        ----------
+        key : str
+            Key to retrieve
+        default : Any, optional
+            Default value if key is not found.
+        set_attr : bool, optional
+            If True (default), set :attr:`source.attrs[key]` to :attr:`params[key]` if found.
+            This allows for better post model evaluation tracking.
+
+        Returns
+        -------
+        Any
+            Value(s) found for key in source data, source attrs, or model params
+
+        Raises
+        ------
+        KeyError
+            Raises KeyError if key is not found in any location and ``default`` is not provided.
+
+        See Also
+        --------
+        get_data_param
+        pycontrails.core.vector.GeoVectorDataset.get_data_or_attr
+        """
+        return self.get_data_param(self.source, key, default, set_attr=set_attr)
+
     def _cleanup_indices(self) -> None:
         """Cleanup indices artifacts if ``params["interpolation_use_indices"]`` is True."""
         if self.params["interpolation_use_indices"] and isinstance(self.source, GeoVectorDataset):