Pycontrails

Features

- Add functionality to automatically compare simulated contrails from `cocip.Cocip` with GOES satellite imagery (`compare_cocip_with_goes`).

Internals

- Fix documentation build in CI.

Breaking changes

- Average fuel burn in the PS model is increased by 2.5\% unless `engine_deterioration_factor` is overriden.

Features

- PS model: Support four aircraft types, including `E75L`, `E75S`, `E290`, and `E295`.
- PS model: Integrate `ps_synonym_list` to increase PS model aircraft type coverage to 102.
- PS model: Account for increase in fuel consumption due to engine deterioration between maintenance cycle.

Internals

- Calculate rate of climb and descent (ROCD) using hydrostatic equation to improve accuracy.
- PS model: Move engine performance buffer from `c_t_available` to `tr_max`.
- Set `tr_max` buffer to +20%, as recommended by Ian Poll.

Breaking changes

- Geodesic interpolation is now used in `Flight.resample_and_fill` when the great circle distance between waypoints (rather than the total segment length including vertical displacement) exceeds a threshold. This may change the interpolation method used when resampling flight segments with lengths close to the geodesic interpolation threshold.
- Fixed typo in `thermo.c_pm` will decrease computed values of moist heat capacity with non-zero specific humidity. We expect the downstream impact on contrail predictions by `ISSR`, `SAC`, `PCR`, and `Cocip` models to be minimal.
- `np.nan` is now used as the default `fill_value` in `MetDataArray.to_polygon_feature` and `MetDataArray.to_polygon_feature_collection`. This ensures that NaN values are never included in polygon interiors unless a non-NaN `fill_value` is explicitly passed as a keyword argument.

Features

- Add `ERA5ModelLevel` and `HRESModelLevel` interfaces for accessing ERA5 and HRES data on model levels.
- Update [ECMWF tutorial notebook](https://py.contrails.org/notebooks/ECMWF.html) with instructions for using model-level datalibs.
- Add `HistogramMatching` humidity scaling calibrated for model-level ERA5 data.
- Modify `polygon.find_multipolygon`, `MetDataArray.to_polygon_feature`, `MetDataArray.to_polygon_feature_collection`, and `MetDataArray.to_polyhedra` to permit finding regions with values above or below a threshold.

Fixes

- Use horizontal great circle distance to determine whether geodesic interpolation is used in `Flight.resample_and_fill`. This ensures geodesic interpolation is used between sufficiently distant waypoints even when one or both waypoints contain NaN altitude data.
- Fix typo in moist heat capacity equation `thermo.c_pm`.

Internals

- Create static copy of dataframe for determining pressure at ECMWF model levels.
- Extract model-level utilities in `ARCOERA5` to their own module for reuse in `ERA5ModelLevel` and `HRESModelLevel`.
- Update Makefile so `make ensure-era5-cached` uses default cache directory when run locally.
- Bump pinned black and ruff versions.
- Disable mypy type checking on `functools.wraps` in `support_arraylike` decorator to avoid error that appears starting on mypy 1.10.0.
- Update pinned `Cocip` test output values after moist heat capacity bugfix.
- Add static files with ECMWF model levels and model-level ERA5 RHI quantiles to packaged data.
- Pass `exc_type=ImportError` to `pytest.importorskip` in test fixtures that use pycontrails extensions to suppress pytest warning when extensions are not installed.
- Bump minimum pytest version 8.2 to ensure the `exc_type` kwarg is available.

Breaking changes

- Replaces engine-uid `01P10IA024` with `04P10IA027` (superseded in the IACO EDB).

Features

- Adds support for the `E190` aircraft type in the PS model
- Adds `Flight.distance_to_coords` which takes in a distance along a flight trajectory in meters and returns geodesic coordinates.
- Adds methods to `ps_operational_limits` to find the maximum and minimum mach numbers for a given set of operating conditions.
- Updates ICAO aircraft engine emissions databank (EDB) from v28c to v29b.

Internals

- New data for gaseous and nvPM emissions for PW812D, PW812GA, RR Trent 7000 with improved nvPM combustor
- Update nvPM emissions for IAE V2530-A5, PW1500G and PW1900G
- Update PS model coeffiencts to match the latest version provided by Ian Poll

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.

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.