pycontrails 0.49.5__tar.gz → 0.50.1__tar.gz

{pycontrails-0.49.5 → 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.49.5 → pycontrails-0.50.1}/CHANGELOG.md

@@ -1,11 +1,65 @@
 
 # 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
+
+- Add `ARCOERA5` interface for accessing ARCO ERA5 model level data. This interface requires the [metview](https://metview.readthedocs.io/en/latest/python.html) python package.
+- Add [ARCO ERA5 tutorial notebook](https://py.contrails.org/notebooks/ARCO-ERA5.html) highlighting the new interface.
+- Add support to output contrail warming impact in ATR20
+
+### Breaking changes
+
+- Reduce `CocipParams.met_level_buffer` from `(200, 200)` to `(40, 40)`. This change is motivated by the observation that the previous buffer was unnecessarily large and caused additional memory overhead. The new buffer is more in line with the typical vertical advection path of a contrail.
+
+### Fixes
+
+- Raise ValueError when `list[Flight]` source is provided to `Cocip` and the `copy_source` parameter is set to `False`. Previously the source was copied in this case regardless of the `copy_source` parameter.
+- Fix broken link in the [model level notebook](https://py.contrails.org/notebooks/model-levels.html).
+
+### Internals
+
+- The `datalib.parse_pressure_levels` now sorts the pressure levels in ascending order and raises a ValueError if the input pressure levels are duplicated or have mixed signs.
+- Add new `MetDataSource.is_single_level` property.
+- Add `ecmwf.Divergence` (a subclass of `MetVariable`) for accessing ERA5 divergence data.
+- Update the [specific humidity interpolation notebook](https://py.contrails.org/notebooks/specific-humidity-interpolation.html) to use the new `ARCOERA5` interface.
+- Adds two parameters to `CoCipParams`, `compute_atr20` and `global_rf_to_atr20_factor`. Setting the former to `True` will add both `global_yearly_mean_rf` and `atr20` to the CoCiP output. 
+- Bump minimum pytest version to 8.1 to avoid failures in release workflow.
+
 ## v0.49.5
 
-## Fixes
+### Fixes
 
-- Fix bug where `Cocip._process_rad` lost radiation dataset attributes
+- Fix bug in which `Cocip._process_rad` dropped radiation dataset attributes introduced in v0.49.4.
 
 ## v0.49.4
 

{pycontrails-0.49.5 → pycontrails-0.50.1}/Makefile

@@ -72,7 +72,7 @@ dev-pycontrails-bada:
 # -----------
 
 ruff: black-check
-	ruff pycontrails tests
+	ruff check pycontrails tests
 
 black:
 	black pycontrails tests
@@ -207,6 +207,7 @@ nb-test: ensure-era5-cached nb-clean-check nb-black-check nb-check-links
 		--ignore=docs/notebooks/GFS.ipynb \
 		--ignore=docs/notebooks/run-cocip-on-flight.ipynb \
 		--ignore=docs/notebooks/model-levels.ipynb \
+		--ignore=docs/notebooks/ARCO-ERA5.ipynb \
 		docs/notebooks docs/integrations
 
 # Check for broken links in notebooks

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pycontrails
-Version: 0.49.5
+Version: 0.50.1
 Summary: Python library for modeling aviation climate impacts
 Author-email: Breakthrough Energy <py@contrails.org>
 License: Apache-2.0
@@ -47,7 +47,7 @@ Requires-Dist: platformdirs>=3.0; extra == "dev"
 Requires-Dist: pre-commit>=2.10; extra == "dev"
 Requires-Dist: psutil; extra == "dev"
 Requires-Dist: pyarrow>=5.0; extra == "dev"
-Requires-Dist: pytest>=6.1; extra == "dev"
+Requires-Dist: pytest>=8.1; extra == "dev"
 Requires-Dist: pytest-cov>=2.11; extra == "dev"
 Requires-Dist: requests>=2.25; extra == "dev"
 Requires-Dist: ruff==0.1.15; extra == "dev"
@@ -72,6 +72,7 @@ Requires-Dist: ecmwf-api-client>=1.6; extra == "ecmwf"
 Requires-Dist: netcdf4>=1.6.1; extra == "ecmwf"
 Requires-Dist: platformdirs>=3.0; extra == "ecmwf"
 Requires-Dist: requests>=2.25; extra == "ecmwf"
+Requires-Dist: lxml>=5.1.0; extra == "ecmwf"
 Provides-Extra: gcp
 Requires-Dist: google-cloud-storage>=2.1; extra == "gcp"
 Requires-Dist: platformdirs>=3.0; extra == "gcp"
@@ -102,6 +103,7 @@ Requires-Dist: seaborn>=0.11; extra == "vis"
 Requires-Dist: shapely>=2.0; extra == "vis"
 Provides-Extra: zarr
 Requires-Dist: fsspec>=2022.7.1; extra == "zarr"
+Requires-Dist: gcsfs>=2022.7.1; extra == "zarr"
 Requires-Dist: zarr>=2.12; extra == "zarr"
 
 # pycontrails

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

@@ -50,6 +50,18 @@
   howpublished = {https://www.movable-type.co.uk/scripts/latlong.html}
 }
 
+@inproceedings{carverARCOERA5AnalysisReadyCloudOptimized2023,
+  title = {{{ARCO-ERA5}}: {{An Analysis-Ready Cloud-Optimized Reanalysis Dataset}}},
+  shorttitle = {{{ARCO-ERA5}}},
+  booktitle = {103rd {{AMS Annual Meeting}}},
+  author = {Carver, Robert W. and Merose, Alex},
+  year = {2023},
+  month = jan,
+  publisher = {{AMS}},
+  urldate = {2024-03-05},
+  abstract = {In this paper, we describe the design and methodology of creating an analysis-r...}
+}
+
 @article{celikel2001forecasting,
   title = {Forecasting Civil Aviation Fuel Burn and Emissions in {{Europe}}},
   author = {Celikel, A and Jelinek, F},
@@ -268,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.},
@@ -700,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.},
@@ -857,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},
@@ -967,3 +1016,21 @@
   abstract = {{$<$}p{$><$}strong class="journal-contentHeaderColor"{$>$}Abstract.{$<$}/strong{$>$} The global commercial aircraft fleet in 2006 flew 31.26 million flights, burned 188.20 million metric tons of fuel, and covered 38.68 billion kilometers. This activity emitted substantial amounts of fossil-fuel combustion products within the upper troposphere and lower stratosphere that affect atmospheric composition and climate. The emissions products, such as carbon monoxide, carbon dioxide, oxides of nitrogen, sulfur compounds, and particulate matter, are not emitted uniformly over the Earth, so understanding the temporal and spatial distributions is important for modeling aviation's climate impacts. Global commercial aircraft emission data for 2004 and 2006, provided by the Volpe National Transportation Systems Center, were computed using the Federal Aviation Administration's Aviation Environmental Design Tool (AEDT). Continuous improvement in methodologies, including changes in AEDT's horizontal track methodologies, and an increase in availability of data make some differences between the 2004 and 2006 inventories incomparable. Furthermore, the 2004 inventory contained a significant over-count due to an imperfect data merge and daylight savings error. As a result, the 2006 emissions inventory is considered more representative of actual flight activity. Here, we analyze both 2004 and 2006 emissions, focusing on the latter, and provide corrected totals for 2004. Analysis of 2006 flight data shows that 92.5\% of fuel was burned in the Northern Hemisphere, 69.0\% between 30N and 60N latitudes, and 74.6\% was burned above 7 km. This activity led to 162.25 Tg of carbon from CO\textsubscript{2} emitted globally in 2006, more than half over three regions: the United States (25.5\%), Europe (14.6), and East Asia (11.1). Despite receiving less than one percent of global emissions, the Arctic receives a uniformly dispersed concentration of emissions with 95.2\% released at altitude where they have longer residence time than surface emissions. Finally, 85.2\% of all flights by number in 2006 were short-haul missions, yet those flights were responsible for only 39.7\% of total carbon from CO\textsubscript{2}. The following is a summary of these data which illustrates the global and regional aviation emissions footprints for 2004 and 2006, and provides temporal and spatial distribution statistics.{$<$}/p{$>$}},
   langid = {english}
 }
+
+@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.49.5 → pycontrails-0.50.1}/docs/api.rst

@@ -71,6 +71,15 @@ GFS
     datalib.gfs.variables
 
 
+ARCO ERA5
+"""""""""
+
+.. autosummary::
+    :toctree: api/
+
+    datalib.ecmwf.arco_era5
+
+
 GOES
 """"
 

{pycontrails-0.49.5 → pycontrails-0.50.1}/docs/meteorology.rst

@@ -11,3 +11,4 @@ Meteorology
    notebooks/Meteorology
    notebooks/ECMWF
    notebooks/GFS
+   notebooks/ARCO-ERA5