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.

v0.47.1

Fixes

• Fix bug in PSGrid in which the met data was assumed to be already loaded into memory. This caused errors when running PSGrid with a MetDataset source.
• Fix bug (#86) in which Cocip.eval loses the source fuel type. Instead of instantiating a new Flight or Fleet instance with the default fuel type, the Cocip._bundle_results method now overwrites the self.source.data attribute with the bundled predictions.
• Avoid a memory explosion when running Cocip on a large non-dask-backed met parameter. Previously the tau_cirrus computation would be performed in memory over the entire met dataset.
• Replace datetime.utcfromtimestamp (deprecated in python 3.12) with datetime.fromtimestamp.
• Explicitly support python 3.12 in the pyproject.toml build system.

Internals

• Add compute_tau_cirrus_in_model_init parameter to CocipParams. This controls whether to compute the cirrus optical depth in Cocip.__init__ or Cocip.eval. When set to "auto" (the default), the tau_cirrus is computed in Cocip.__init__ if and only if the met parameter is dask-backed.
• Change data requirements for the EmpiricalGrid aircraft performance model.
• Consolidate ERA5.cache_dataset and HRES.cache_dataset onto common ECMWFAPI.cache_dataset method. Previously the child implementations were identical.
• No longer require the pyproj package as a dependency. This is now an optional dependency, and can be installed with pip install pycontrails[pyproj].

v0.47.0

Implement a Poll-Schumann (PSGrid) theoretical aircraft performance model over a grid.

Breaking changes

• Move the pycontrails.models.aircraft_performance module to pycontrails.core.aircraft_performance.
• Rename PSModel -> PSFlight.

Fixes

• Use the instance fuel attribute in the Fleet.to_flight_list method. Previously, the default JetA fuel was always used.
• Ensure the Fleet.fuel attribute is inferred from the underlying sequence of flights in the Fleet.from_seq method.

Features

• Implement the PSGrid model. For a given aircraft type and position, this model computes optimal aircraft performance at cruise conditions. In particular, this model can be used to estimate fuel flow, engine efficiency, and aircraft mass at cruise. In particular, the PSGrid model can now be used in conjunction with CocipGrid to simulate contrail formation over a grid.
• Refactor the Emissions model so that Emissions.eval runs with source: GeoVectorDataset. Previously, the eval method required a Flight instance for the source parameter. This change allows the Emissions model to run more seamlessly as a sub-model of a gridded model (ie, CocipGrid),
• No longer require pycontrails-bada to import or run the CocipGrid model. Instead, the CocipGridParams.aircraft_performance parameter can be set to any AircraftPerformanceGrid instance. This allows the CocipGrid model to run with any aircraft performance model that implements the AircraftPerformanceGrid interface.
• Add experimental EmpiricalAircraftPerformanceGrid model.
• Add convenience GeoVectorDataset.T_isa method to compute the ISA temperature at each point.

Internals

• Add optional climb_descend_at_end parameter to the Flight.resample_and_fill method. If True, the climb or descent will be placed at the end of each segment rather than the start.
• Define AircraftPerformanceGridParams, AircraftPerformanceGrid, and AircraftPerformanceGridData abstract interfaces for gridded aircraft performance models.
• Add set_attr parameter to Models.get_source_param.
• Better handle source, source.attrs, and params customizations in CocipGrid.
• Include additional classes and functions in the pycontrails.models.emissions module.
• Hardcode the paths to the static data files used in the Emissions and PSFlight models. Previously these were configurable by model parameters.
• Add altitude_ft parameter to the GeoVectorDataset constructor. Warn if at least two of altitude_ft, altitude, and level are provided.
• Allow instantiation of Model instances with params: ModelParams. Previously, the params parameter was required to be a dict. The current implementation checks that the params parameter is either a dict or has type default_params on the Model class.