pycontrails 0.49.5__tar.gz → 0.50.0__tar.gz

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

@@ -1,11 +1,37 @@
 
 # Changelog
 
+## 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.0}/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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pycontrails
-Version: 0.49.5
+Version: 0.50.0
 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.0}/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},
@@ -967,3 +979,23 @@
   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{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},
+}

{pycontrails-0.49.5 → pycontrails-0.50.0}/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.0}/docs/meteorology.rst

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