pycontrails 0.50.0__tar.gz → 0.50.1__tar.gz

{pycontrails-0.50.0 → pycontrails-0.50.1}/.github/workflows/release.yaml

@@ -40,7 +40,7 @@ jobs:
 
       # https://cibuildwheel.readthedocs.io/en/stable/options/#testing
       - name: Build wheels
-        uses: pypa/cibuildwheel@v2.16
+        uses: pypa/cibuildwheel@v2.17
         env:
           CIBW_BUILD: cp39-* cp310-* cp311-* cp312-*
           CIBW_SKIP: '*-win32 *-manylinux_i686 *-musllinux*'

{pycontrails-0.50.0 → pycontrails-0.50.1}/CHANGELOG.md

@@ -1,6 +1,34 @@
 
 # Changelog
 
+## v0.50.1
+
+### Breaking changes
+
+- Updates to flight resampling logic now ensure that resampled waypoints include any and all times between flight start and end times that are a multiple of the resampling frequency. This may add an additional waypoint to some flights after resampling, and may result in `Flight.resample_and_fill` returning a flight with a single waypoint rather than an empty flight.
+
+### Features
+
+- Refine CoCiP contrail initialization model based on the work of Unterstrasser (2016, doi:10.5194/acp-16-2059-2016) and Karcher (2018, doi:10.1038/s41467-018-04068-0).
+  - This update implements a refined parameterization of the survival fraction of contrail ice crystal number after the wake vortex phase (`f_surv`). The parameterised model was developed by Unterstrasser (2016) based on outputs provided by large eddy simulations, and improves agreement with LES output relative to the default survival fraction parameterization in CoCiP.
+  - These changes replicate Fig. 4 of Karcher (2018), where `f_surv` now depends on the initial number of ice crystals. These effects are particularly important, especially in the "soot-poor" scenario where the number fraction of contrail ice crystals that survives the wake vortex phase could be larger than the mass fraction, because the particles are larger in size.
+  - This also improves upon the existing assumption in CoCiP, where the survival fraction is estimated as the change in contrail ice water content (by mass) before and after the wake vortex phase.
+The Unterstrasser (2016) parameterization can be used in CoCiP by setting a new parameter, `unterstrasser_ice_survival_fraction`, to `True`.
+- Adds optional ATR20 to CoCiPGrid model.
+
+### Fixes
+
+- Update flight resampling logic to align with expected behavior for very short flights, which is now detailed in the `Flight.resample_and_fill` docstring.
+
+### Internals
+  
+- Adds a parameter to `CoCipParams`, `unterstrasser_ice_survival_fraction`, that activates the Unterstrasser (2016) survival parameterization when set to `True`. This is disabled by default, and only implemented for `CoCiP`. `CoCiPGrid` will produce an error if run with `unterstrasser_ice_surival_fraction=True`.
+- Modifies `CoCiPGrid` so that setting `compute_atr_20` (defined in `CoCipParams`) to `True` adds `global_yearly_mean_rf` and `atr20` to CoCiP-grid output.
+- Replaces `pycontrails.datalib.GOES` ash convention label "MIT" with "SEVIRI"
+- Modifies meteorology time step selection logic in `CoCiPGrid` to reduce duplicate chunk downloads when reading from remote zarr stores.
+- Updates unit tests for xarray v2024.03.0, which introduced changes to netCDF decoding that slightly alter decoded values. Note that some unit tests will fail for earlier xarray versions.
+- Updates `RegularGridInterpolator` to fall back on legacy scipy implementations of tensor-product spline methods when using scipy versions 1.13.0 and later.
+
 ## v0.50.0
 
 ### Features

{pycontrails-0.50.0 → pycontrails-0.50.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pycontrails
-Version: 0.50.0
+Version: 0.50.1
 Summary: Python library for modeling aviation climate impacts
 Author-email: Breakthrough Energy <py@contrails.org>
 License: Apache-2.0

{pycontrails-0.50.0 → pycontrails-0.50.1}/docs/_static/pycontrails.bib

@@ -280,6 +280,20 @@
   langid = {english}
 }
 
+@article{karcherFormationRadiativeForcing2018,
+  title = {Formation and Radiative Forcing of Contrail Cirrus},
+  author = {K{\"a}rcher, Bernd},
+  year = {2018},
+  month = dec,
+  journal = {Nature Communications},
+  volume = {9},
+  number = {1},
+  issn = {2041-1723},
+  doi = {10.1038/s41467-018-04068-0},
+  urldate = {2020-12-18},
+  langid = {english}
+}
+
 @article{khanEmissionsWaterVapour2022,
   title = {The {{Emissions}} of {{Water Vapour}} and {{NOx}} from {{Modelled Hydrogen-Fuelled Aircraft}} and the {{Impact}} of {{NOx Reduction}} on {{Climate Compared}} with {{Kerosene-Fuelled Aircraft}}},
   author = {Khan, M. Anwar H. and Brierley, Joel and Tait, Kieran N. and Bullock, Steve and Shallcross, Dudley E. and Lowenberg, Mark H.},
@@ -712,6 +726,12 @@
   langid = {english}
 }
 
+@misc{SEVIRIRGBCal,
+  title = {{{SEVIRI RGB Cal Module}} - Part {{II}}},
+  urldate = {2024-03-29},
+  howpublished = {https://resources.eumetrain.org/data/4/410/navmenu.php?tab=5\&page=2.0.0}
+}
+
 @article{sonntag1994,
   title = {Advancements in the Field of Hygrometry},
   author = {Sonntag, D.},
@@ -869,6 +889,23 @@
   abstract = {Sustainable aviation fuel (SAF) can reduce aviation's CO2 and non-CO2 impacts. We quantify the change in contrail properties and climate forcing in the North Atlantic resulting from different blending ratios of SAF and demonstrate that intelligently allocating the limited SAF supply could multiply its overall climate benefit by factors of 9\textendash 15. A fleetwide adoption of 100\% SAF increases contrail occurrence (+5\%), but lower nonvolatile particle emissions (-52\%) reduce the annual mean contrail net radiative forcing (-44\%), adding to climate gains from reduced life cycle CO2 emissions. However, in the short term, SAF supply will be constrained. SAF blended at a 1\% ratio and uniformly distributed to all transatlantic flights would reduce both the annual contrail energy forcing (EFcontrail) and the total energy forcing (EFtotal, contrails + change in CO2 life cycle emissions) by {$\sim$}0.6\%. Instead, targeting the same quantity of SAF at a 50\% blend ratio to {$\sim$}2\% of flights responsible for the most highly warming contrails reduces EFcontrail and EFtotal by {$\sim$}10 and {$\sim$}6\%, respectively. Acknowledging forecasting uncertainties, SAF blended at lower ratios (10\%) and distributed to more flights ({$\sim$}9\%) still reduces EFcontrail ({$\sim$}5\%) and EFtotal ({$\sim$}3\%). Both strategies deploy SAF on flights with engine particle emissions exceeding 1012 m\textendash 1, at night-time, and in winter.}
 }
 
+@article{unterstrasserPropertiesYoungContrails2016,
+  title = {Properties of Young Contrails \– a Parametrisation Based on Large-Eddy Simulations},
+  author = {Unterstrasser, Simon},
+  year = {2016},
+  month = feb,
+  journal = {Atmospheric Chemistry and Physics},
+  volume = {16},
+  number = {4},
+  pages = {2059--2082},
+  publisher = {{Copernicus GmbH}},
+  issn = {1680-7316},
+  doi = {10.5194/acp-16-2059-2016},
+  urldate = {2023-08-23},
+  abstract = {Contrail\–cirrus is probably the largest climate forcing from aviation. The evolution of contrail\–cirrus and its radiative impact depends not only on a multitude of atmospheric parameters, but also on the geometric and microphysical properties of the young contrails evolving into contrail\–cirrus. The early evolution of contrails (t \< 5 min) is dominated by an interplay of ice microphysics and wake vortex dynamics. Young contrails may undergo a fast vertical expansion due to a descent of the wake vortices and may lose a substantial fraction of their ice crystals due to adiabatic heating. The geometric depth H and total ice crystal number N of young contrails are highly variable and depend on many environmental and aircraft parameters. Both properties, H and N, affect the later properties of the evolving contrail\–cirrus, as they control the extent of shear-induced spreading and sedimentation losses. In this study, we provide parametrisations of H and N after 5 min taking into account the effects of temperature, relative humidity, thermal stratification and aircraft type (mass, wing span, fuel burn). The parametrisations rely on a large data set of recent large-eddy simulations of young contrails. They are suited to be incorporated in larger-scale models in order to refine the present-day contrail initialisations by considering the processes that strongly affect the contrail evolution during the vortex phase.},
+  langid = {english}
+}
+
 @misc{uosolarradiationmonitoringlaboratoryUOSRMLSolar2022,
   title = {{{UO SRML}}: {{Solar}} Radiation Basics},
   author = {UO Solar Radiation Monitoring Laboratory},
@@ -980,22 +1017,20 @@
   langid = {english}
 }
 
-
-@article{yin_predicting_2023,
-	title = {Predicting the climate impact of aviation for en-route emissions: the algorithmic climate change function submodel {ACCF} 1.0 of {EMAC} 2.53},
-	volume = {16},
-	issn = {1991-959X},
-	shorttitle = {Predicting the climate impact of aviation for en-route emissions},
-	url = {https://gmd.copernicus.org/articles/16/3313/2023/},
-	doi = {10.5194/gmd-16-3313-2023},
-	abstract = {Using climate-optimized flight trajectories is one essential measure to reduce aviation's climate impact. Detailed knowledge of temporal and spatial climate sensitivity for aviation emissions in the atmosphere is required to realize such a climate mitigation measure. The algorithmic Climate Change Functions (aCCFs) represent the basis for such purposes. This paper presents the first version of the Algorithmic Climate Change Function submodel (ACCF 1.0) within the European Centre HAMburg general circulation model (ECHAM) and Modular Earth Submodel System (MESSy) Atmospheric Chemistry (EMAC) model framework. In the ACCF 1.0, we implement a set of aCCFs (version 1.0) to estimate the average temperature response over 20 years (ATR20) resulting from aviation CO2 emissions and non-CO2 impacts, such as NOx emissions (via ozone production and methane destruction), water vapour emissions, and contrail cirrus. While the aCCF concept has been introduced in previous research, here, we publish a consistent set of aCCF formulas in terms of fuel scenario, metric, and efficacy for the first time. In particular, this paper elaborates on contrail aCCF development, which has not been published before. ACCF 1.0 uses the simulated atmospheric conditions at the emission location as input to calculate the ATR20 per unit of fuel burned, per NOx emitted, or per flown kilometre. In this research, we perform quality checks of the ACCF 1.0 outputs in two aspects. Firstly, we compare climatological values calculated by ACCF 1.0 to previous studies. The comparison confirms that in the Northern Hemisphere between 150–300 hPa altitude (flight corridor), the vertical and latitudinal structure of NOx-induced ozone and H2O effects are well represented by the ACCF model output. The NOx-induced methane effects increase towards lower altitudes and higher latitudes, which behaves differently from the existing literature. For contrail cirrus, the climatological pattern of the ACCF model output corresponds with the literature, except that contrail-cirrus aCCF generates values at low altitudes near polar regions, which is caused by the conditions set up for contrail formation. Secondly, we evaluate the reduction of NOx-induced ozone effects through trajectory optimization, employing the tagging chemistry approach (contribution approach to tag species according to their emission categories and to inherit these tags to other species during the subsequent chemical reactions). The simulation results show that climate-optimized trajectories reduce the radiative forcing contribution from aviation NOx-induced ozone compared to cost-optimized trajectories. Finally, we couple the ACCF 1.0 to the air traffic simulation submodel AirTraf version 2.0 and demonstrate the variability of the flight trajectories when the efficacy of individual effects is considered. Based on the 1 d simulation results of a subset of European flights, the total ATR20 of the climate-optimized flights is significantly lower (roughly 50 \% less) than that of the cost-optimized flights, with the most considerable contribution from contrail cirrus. The CO2 contribution observed in this study is low compared with the non-CO2 effects, which requires further diagnosis.},
-	language = {English},
-	number = {11},
-	urldate = {2023-08-23},
-	journal = {Geoscientific Model Development},
-	author = {Yin, Feijia and Grewe, Volker and Castino, Federica and Rao, Pratik and Matthes, Sigrun and Dahlmann, Katrin and Dietmüller, Simone and Frömming, Christine and Yamashita, Hiroshi and Peter, Patrick and Klingaman, Emma and Shine, Keith P. and Lührs, Benjamin and Linke, Florian},
-	month = jun,
-	year = {2023},
-	note = {Publisher: Copernicus GmbH},
-	pages = {3313--3334},
+@article{yinPredictingClimateImpact2023,
+  title = {Predicting the Climate Impact of Aviation for En-Route Emissions: The Algorithmic Climate Change Function Submodel {{ACCF}} 1.0 of {{EMAC}} 2.53},
+  shorttitle = {Predicting the Climate Impact of Aviation for En-Route Emissions},
+  author = {Yin, Feijia and Grewe, Volker and Castino, Federica and Rao, Pratik and Matthes, Sigrun and Dahlmann, Katrin and Dietm{\"u}ller, Simone and Fr{\"o}mming, Christine and Yamashita, Hiroshi and Peter, Patrick and Klingaman, Emma and Shine, Keith P. and L{\"u}hrs, Benjamin and Linke, Florian},
+  year = {2023},
+  month = jun,
+  journal = {Geoscientific Model Development},
+  volume = {16},
+  number = {11},
+  pages = {3313--3334},
+  publisher = {{Copernicus GmbH}},
+  issn = {1991-959X},
+  doi = {10.5194/gmd-16-3313-2023},
+  urldate = {2023-08-23},
+  abstract = {Using climate-optimized flight trajectories is one essential measure to reduce aviation's climate impact. Detailed knowledge of temporal and spatial climate sensitivity for aviation emissions in the atmosphere is required to realize such a climate mitigation measure. The algorithmic Climate Change Functions (aCCFs) represent the basis for such purposes. This paper presents the first version of the Algorithmic Climate Change Function submodel (ACCF 1.0) within the European Centre HAMburg general circulation model (ECHAM) and Modular Earth Submodel System (MESSy) Atmospheric Chemistry (EMAC) model framework. In the ACCF 1.0, we implement a set of aCCFs (version 1.0) to estimate the average temperature response over 20 years (ATR20) resulting from aviation CO2 emissions and non-CO2 impacts, such as NOx emissions (via ozone production and methane destruction), water vapour emissions, and contrail cirrus. While the aCCF concept has been introduced in previous research, here, we publish a consistent set of aCCF formulas in terms of fuel scenario, metric, and efficacy for the first time. In particular, this paper elaborates on contrail aCCF development, which has not been published before. ACCF 1.0 uses the simulated atmospheric conditions at the emission location as input to calculate the ATR20 per unit of fuel burned, per NOx emitted, or per flown kilometre.  In this research, we perform quality checks of the ACCF 1.0 outputs in two aspects. Firstly, we compare climatological values calculated by ACCF 1.0 to previous studies. The comparison confirms that in the Northern Hemisphere between 150\textendash 300 hPa altitude (flight corridor), the vertical and latitudinal structure of NOx-induced ozone and H2O effects are well represented by the ACCF model output. The NOx-induced methane effects increase towards lower altitudes and higher latitudes, which behaves differently from the existing literature. For contrail cirrus, the climatological pattern of the ACCF model output corresponds with the literature, except that contrail-cirrus aCCF generates values at low altitudes near polar regions, which is caused by the conditions set up for contrail formation. Secondly, we evaluate the reduction of NOx-induced ozone effects through trajectory optimization, employing the tagging chemistry approach (contribution approach to tag species according to their emission categories and to inherit these tags to other species during the subsequent chemical reactions). The simulation results show that climate-optimized trajectories reduce the radiative forcing contribution from aviation NOx-induced ozone compared to cost-optimized trajectories. Finally, we couple the ACCF 1.0 to the air traffic simulation submodel AirTraf version 2.0 and demonstrate the variability of the flight trajectories when the efficacy of individual effects is considered. Based on the 1 d simulation results of a subset of European flights, the total ATR20 of the climate-optimized flights is significantly lower (roughly 50 \% less) than that of the cost-optimized flights, with the most considerable contribution from contrail cirrus. The CO2 contribution observed in this study is low compared with the non-CO2 effects, which requires further diagnosis.},
+  langid = {english}
 }

{pycontrails-0.50.0 → pycontrails-0.50.1}/pycontrails/_version.py

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

{pycontrails-0.50.0 → pycontrails-0.50.1}/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-0.50.0 → pycontrails-0.50.1}/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-0.50.0 → pycontrails-0.50.1}/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()
@@ -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: