v0.52.1

Breaking changes

• Remove lock=False as a default keyword argument to xr.open_mfdataset in the MetDataSource.open_dataset method. This reverts a change from v0.44.1 and prevents segmentation faults when using recent versions of netCDF4 (1.7.0 and above).
• GOES imagery is now loaded from a temporary file on disk rather than directly from memory when using GOES.get without a cachestore.

Internals

• Remove upper limits on netCDF4 and numpy versions.
• Remove h5netcdf dependency.
• Update doctests with numpy 2 scalar representation (see NEP 51). Doctests will now fail when run with numpy 1.
• Run certain tests in test_ecmwf.py and test_met.py using the single-threaded dask scheduler to prevent tests from hanging while waiting for a lock that is never released. (This issue was encountered previously, and removing lock=False in MetDataSource.open_dataset reverts the fix.)
• Document pycontrails installation from conda-forge.

Fixes

• Ensure the MetDataset vertical coordinates "air_pressure" and "altitude" have the correct dtype.

v0.52.0

Breaking changes

• The _antimeridian_index helper method in the flight module now returns a list of integers rather than an integer. This allows Flight.to_geojson_multilinestring to support multiple antimeridian crossings (see below).

Features

• Add tools for running APCEMM from within pycontrails. This includes:
  • utilities for generating APCEMM input files and running APCEMM (pycontrails.models.apcemm.utils)
  • an interface (pycontrails.models.apcemm.apcemm) that allows users to run APCEMM as a pycontrails Model.
• Add APCEMM tutorial notebook.
• Add prescribed sedimentation rate to DryAdvection model.
• Add Landsat and Sentinel datalibs for searching, retrieving, and visualizing Landsat 8-9 and Sentinel-2 imagery. The datalibs include:
  • Tools for querying Landsat and Sentinel-2 imagery for intersections with user-defined regions (landsat.query, sentinel.query) or flights (landsat.intersect, sentinel.intersect). These tools use BigQuery tables and require a Google Cloud Platform account with access to the BigQuery API.
  • Tools for downloading and visualizing imagery from Landsat (Landsat) and Sentinel-2 (Sentinel). These tools retrieve data anonymously from Google Cloud Platform storage buckets and can be used without a Google Cloud Platform account.
• Add tutorial notebooks demonstrating how to use Landsat and Sentinel datalibs to find flights in high-resolution satellite imagery.
• Modify Flight.to_geojson_multilinestring to make grouping key optional and to support multiple antimeridian crossings.
• Update the pycontrails build system to require numpy 2.0 per the official numpy guidelines. Note that the runtime requirement for pycontrails remains numpy>=1.22.
• Update pycontrails for breaking changes introduced in numpy 2.0 (e.g., NEP 50). All changes are backward compatible with numpy>=1.22.

Fixes

• Ensure width and depth are never attached to DryAdvection source when running pointwise-only model.
• Ensure that azimuth is not dropped when present in DryAdvection input source.
• Exclude netCDF version 1.7.0, which causes non-deterministic failures in unit tests primarily due to segmentation faults.
• Pin numpy to 1.x in runtime dependencies until a working numpy 2.x-compatible netCDF4 release is available.

Internals

• Create unit tests for the APCEMM interface that run if an APCEMM executable is found on the PATH inside a clean APCEMM git repository with a pinned git hash. These tests will be skipped unless users carefully configure their local test environment and will not run in CI.
• Exclude APCEMM tutorial notebook from notebook tests.
• Add unit tests for Landsat and Sentinel search tools and datalibs, but disable any tests that retrieve imagery data when running tests in GitHub Actions to limit resource consumption in GitHub runners. Users can disable these units tests locally by setting the environment variable GITHUB_ACTIONS=true.
• Ensure GITHUB_ACTIONS environment variable is available when building and testing wheels on linux.
• Skip cells that retrieve imagery data when running tests on Landsat and Sentinel tutorial notebooks.
• Add tests for Flight.to_geojson_multilinestring with grouping key omitted and update tests with multiple antimeridian crossings.
• Minimum pandas version is bumped to 2.2 to ensure the the include_groups keyword argument used in Flight.to_geojson_multilinestring is available.
• Upgrade minimum mypy dependencies

v0.51.2

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

v0.51.1

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.

v0.51.0

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 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.

v0.50.2

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

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 PycontrailsRegularGridInterpolator 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 python package.
• Add ARCO ERA5 tutorial notebook 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.

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 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

• Fix bug where Cocip._process_rad lost radiation dataset attributes

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 (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.