Pycontrails

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.

Fixes

- Fix bug in which `Cocip._process_rad` dropped radiation dataset attributes introduced in v0.49.4.

Breaking changes

- Remove the `CocipGridParams.met_slice_dt` parameter. Now met downselection is handled automatically during contrail evolution. When the `met` and `rad` data passed into `CocipGrid` are not already loaded into memory, this update may make `CocipGrid` slightly more performant.
- No longer explicitly load `met` and `rad` time slices into memory in `CocipGrid`. This now only occurs downstream when interpolation is performed. This change better aligns `CocipGrid` with other pycontrails models.
- Remove the `cocipgrid.cocip_time_handling` module. Any useful tooling has been moved directly to the `cocipgrid.cocip_grid` module.
- Remove the `CocipGrid.timedict` attribute. Add a `CocipGrid.timesteps` attribute. This is now applied in the same manner that the `Cocip` model uses its `timesteps` attribute.
- Simplify the runtime estimate used in constructing the `CocipGrid` `tqdm` progress bar. The new estimate is less precise than the previous estimate and should not be trusted for long-running simulations.
- Deprecate `MetBase.variables` in favor of `MetBase.indexes`.

Features

- Add support for 9 additional aircraft types in the [Poll-Schumann](https://py.contrails.org/notebooks/AircraftPerformance.html) (PS) aircraft performance model. The new aircraft types are:
- A338
- A339
- A35K
- B37M
- B38M
- B39M
- B78X
- BCS1
- BCS3
- Modify PS coefficients for B788, B789, and A359.
- Support running `CocipGrid` on meteorology data without a uniformly-spaced time dimension. The `CocipGrid` implementation now no longer assumes `met["time"].diff()` is constant.
- Add a `MetDataset.downselect_met` method. This performs a met downselection in analogy with `GeoVectorDataset.downselect_met`.

Fixes

- Improve clarity of warnings produced when meteorology data doesn't cover the time range required by a gridded CoCiP model.
- No longer emit `pandas` warning when `Flight.resample_and_fill(..., drop=True, ...)` is called with non-float data.
- Correctly handle `CocipGrid` `rad` data with non-uniform time steps.

Features

- Re-organize notebooks in documentation.
- Add new [model level](https://py.contrails.org/examples/model-levels.html) tutorial notebook.
- Add new high-level `Flight.clean_and_resample` method. This method parallels the `Flight.resample_and_fill` method but performs additional altitude filtering. In essence, this method is a combination of `Flight.filter_altitude` and `Flight.resample_and_fill`.

Breaking changes

- Remove `Flight.fit_altitude` method in favor of `Flight.filter_altitude`. The new method now only applies a median filter during cruise flight phase.

Fixes

- Remove opaque warning issued when all tau_contrail values are nan in `Cocip` evolution.
- Emit warning in `Cocip.eval` if the advected contrail is blown outside of the domain of the met data.
- Remove empty flights in `Fleet.from_seq`. Issue warning if an empty flight is encountered.
- Emit warning when `Flight.resample_and_fill` returns an empty flight.

Internals

- Modify test workflow to use Makefile recipes and ensure early failures are detected in CI.
- Pin `black` and `ruff` versions for consistency between local and CI/CD environments.
- Improve development documentation.
- Improve handling of missing credentials in tests (`make nb-test`, `make doctest`).
- Update time frequency aliases for `pandas` 2.2 compatibility.
- Update cython annotations for `scipy` 1.12 compatibility.
- Improve notebook output testing capabilities (`make nb-test`).
- Add new convenience Make recipe to execute all notebooks in the docs (`make nb-execute`).
- Add new Make recipe to cleanup notebooks (`make nb-clean`).
- Add pre-commit hook to check if notebooks are *clean*.
- Re-organize notebooks in documentation.
- Clean up contributing and develop documentation.
- Automatically parse `np.timedelta64`-like model params in `Model.update_params`.