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.

v0.49.3

Features

• Re-organize notebooks in documentation.
• Add new model level 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.

v0.49.2

Features

• Support pandas Copy-on-Write. This can be enabled with pd.set_option("mode.copy_on_write", True) or by setting the PANDAS_COPY_ON_WRITE environment variable.

Fixes

• Ensure the Flight.fuel attribute is preserved for the Flight.filter method.
• Ensure the Fleet.fl_attrs attribute is preserved for the Fleet.filter method.
• Raise ValueError when Flight.sort or Fleet.sort is called. Both of these subclasses assume a custom sorting order that is enforced in their constructors.
• Always correct intermediate thrust coefficients computed in the PSGrid model. This correction is already enabled by default in the PSFlight model.
• Include attr fields in the ValueError message raised in CocipGrid when not all aircraft performance variables are present on the source parameter.
• Allow mach_number as a replacement for true_airspeed in CocipGrid aircraft performance determination.

Internals

• Make Fuel and its subclasses JetA, SAFBlend, and HydrogenFuel frozen.
• No longer copy met when Models.downselect_met is called. In some modes of operation, this reduces the memory footprint of the model.
• Update codebase for more harmony with PDEP 8 and Copy-on-Write semantics.
• Add default parameter to the VectorDataset.get_data_or_attr method.

v0.49.1

Fixes

• Fix memory bottleneck in CocipGrid simulation by avoiding expensive call to pd.concat.
• Require oldest-supported-numpy for python 3.12. Remove logic for numpy 1.26.0rc1 in the pyproject.toml build system.

v0.49.0

This release updates the Poll-Schumann (PS) aircraft performance model to version 2.0. It also includes a number of bug fixes and internal improvements.

Features

• Add convenience Fleet.resample_and_fill.
• Update the PS model aircraft-engine parameters.
• Improve PS model accuracy in fuel consumption estimates.
• Improve PS model accuracy in overall propulsive efficiency estimates.
• Include additional guardrails in the PS model to constrain the operational limits of different aircraft-engine types, i.e., the maximum permitted Mach number by altitude, maximum available thrust coefficient, maximum lift coefficient, and maximum allowable aircraft mass.

Fixes

• Update polygon algorithm to use shapely.Polygon instead of shapely.LinearRing for contours with at least 4 vertices.
• Fix Fleet.to_flight_list to avoid duplicating global attributes on the child Flight instances.
• Add __slots__ to GeoVectorDataset, Flight, and Fleet. The base VectorDataset class already uses __slots__.
• Add Fleet.copy method.
• Improve Fleet.__init__ implementation.
• Ensure source parameter is mutated in CocipGrid.eval when the model parameter copy_source=False.

v0.48.1

Features

• Generalize met.shift_longitude() to translate longitude coordinates onto any domain bounds.
• Add VectorDataset.to_dict() methods to output Vector data as dictionary. This method enables Flight.to_dict() objects to be serialized for input to the Contrails API.
• Add VectorDataset.from_dict() class method to create VectorDataset class from dictionary.
• Support more time formats, including timezone aware times, in VectorDataset creation. All timezone aware `"time"`` coordinates are converted to UTC and stripped of timezone identifier.

Fixes

• Fix issue in the wake_vortex.max_downward_displacement function in which float32 dtypes were promoted to float64 dtypes in certain cases.
• Ignore empty vectors in VectorDataset.sum.

Internals

• Set frozen=True on the MetVariable dataclass.
• Test against python 3.12 in the GitHub Actions CI. Use python 3.12 in docs and doctest workflows.

v0.48.0

This release includes a number of breaking changes and new features. If upgrading from a previous version of pycontrails, please read the changes below carefully. Open an issue if you experience problems.

Breaking changes

• When running Cocip and other pycontrails models, the met and rad parameter must now contain predefined metadata attributes provider, dataset, and product describing the met source. An error will now be raised in Cocip if these attributes are not present.
• Deprecate passing arbitrary kwargs into the MetDataArray constructor.
• No longer convert accumulated radiation data to average instantaneous data in ERA5 and HRES interfaces. This logic is now handled downstream by the model (e.g., Cocip). This change allows for more flexibility in the rad data passed into the model and avoids unnecessary computation in the MetDataSource interfaces.
• Add new MetDataSource.set_met_source_metadata abstract method. This should be called within the implementing class open_metdataset method.
• No longer take a finite difference in the time dimension for HRES radiation data. This is now also handled natively in Cocip.
• No longer convert relative humidity from a percentage to a fraction in ERA5 and HRES interfaces.
• Require the HRES stream parameter to be one of ["oper", "enfo"]. Require the field_type parameter to be one of ["fc", "pf", "cf", "an"].
• Remove the steps and step_offset properties in the GFSForecast interface. Now the timesteps attribute is the only source of truth for determining AWS S3 keys. Change the filename method to take in a datatime timestep instead of an int step. No longer assign the first step radiation data to the zeroth step.
• Change the return type of ISSR.eval, SAC.eval, and PCR.eval from MetDataArray to MetDataset. This is more consistent with the return type of other pycontrails models and more closely mirrors the behavior of vector models. Set output attrs metadata on the global MetDataset instead of the individual MetDataArray in each case.

Features

• Rewrite parts of the pycontrails.core.datalib module for higher performance and readability.
• Add optional attrs and attrs_kwargs parameters to MetDataset constructor. This allows the user to customize the attributes on the underlying xarray.Dataset object. This update makes MetDataset more consistent with VectorDataset.
• Add three new properties provider_attr, dataset_attr, and product_attr to MetDataset. These properties give metadata describing the underlying meterological data source.
• Add new Model.transfer_met_source_attrs method for more consistent handling of met source metadata on the source parameter passed into Model.eval.
• No longer require geopotential data when computing tau_cirrus. If neither geopotential nor geopotential_height are available, geopotential is approximated from the geometric height. No longer require geopotential on the met parameter in Cocip or CocipGrid.
• Remove the Cocip shift_radiation_time parameter. This is now inferred directly from the rad metadata. An error is raised if the necessary metadata is not present.
• Allow Cocip to run with both instantaneous (W m-2) and accumulated (J m-2) radiation data.
• Allow Cocip to run with accumulated ECMWF HRES radiation data.

Fixes

• Correct radiation unit in the ACCF wrapper model [#64]. Both instantaneous (W m-2) and accumulated (J m-2) radiation data are now supported, and the ACCF wrapper will handle each appropriately.
• Avoid unnecessary writing and reading of temporary files in ERA5.cache_dataset and HRES.cache_dataset.
• Fix timestep resolution bug in GFSForecast. When the grid parameter is 0.5 or 1.0, forecasts are only available every 3 hours. Previously, the timesteps property would define an hourly timestep.

Internals

• Include name parameter in MetDataArray constructor.
• Make the coordinates.slice_domain function slightly more performant by explicitly dropping nan values from the request parameter.
• Round unwieldy floating point numbers in GeoVectorDataset._display_attrs.
• Remove the ecmwflibs package from the ecmwf optional dependencies.
• Add NPY to ruff rules.
• Add convenience MetDataset.standardize_variables method.
• Remove the p_settings attribute on the ACCF interface. This is now constructed internally within ACCF.eval. Replace the ACCF._update_accf_config method with a _get_accf_config function.

v0.47.3

Fixes

• Strengthen correct_fuel_flow in the PSmodel to account for descent conditions.
• Clip the denominator computed in pycontrails.physics.jet.equivalent_fuel_flow_rate_at_cruise.
• Ensure the token used within GitHub workflows has the fewest privileges required. Set top-level permissions to none in each workflow file. Remove unnecessary permissions previously used in the google-github-actions/auth action.
• Fix bug in radiative_forcing.effective_tau_contrail identified in #99.
• Fix the unit for vertical_velocity in geo.advect_level.
• Fix bug appearing in Flight._geodesic_interpolation in which a single initial large gap was not interpolated with a geodesic path.

Internals

• Add FlightPhase to the pycontrails namespace.

v0.47.2

Features

• New experimental GOES interface for downloading and visualizing GOES-16 satellite imagery.
• Add new GOES example notebook highlighting the interface.
• Build python 3.12 wheels for Linux, macOS, and Windows on release. This is in addition to the existing python 3.9, 3.10, and 3.11 wheels.

Fixes

• Use the experimental version number parameter E in pycontrails.ecmwf.hres.get_forecast_filename. Update the logic involved in setting the dissemination data stream indicator S.
• Change the behavior of _altitude_interpolation method that is called within resample_and_fill. Step climbs are now placed in the middle of long flight segments. Descents continue to occur at the end of segments.

Internals

• Provide consistent ModuleNotFoundError messages when optional dependencies are not installed.
• Move the synthetic_flight module into the pycontrails.ext namespace.