pycontrails 0.54.5__tar.gz → 0.54.6__tar.gz

{pycontrails-0.54.5 → pycontrails-0.54.6}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## v0.54.6
+
+### Features
+
+- Add support for generic (model-agnostic) meteorology data to `Cocip` and `CocipGrid`.
+
+- Add two new parameters to the `DryAdvection` model.
+  - If the `verbose_outputs` parameter is enabled, additional wind-shear data is included in the output.
+  - If the `include_source_in_output` parameter is enabled, the source data with any of the intermediate artifacts (e.g., interpolated met data, wind-shear data, etc.) is included in the output.
+
+  Both parameters are disabled by default.
+
+### Fixes
+
+- Update the CDS URL referenced throughout pycontrails from ``https://cds-beta.climate.copernicus.eu`` to ``https://cds.climate.copernicus.eu``.
+
+### Internals
+
+- Suppress mypy `return-value` errors for functions in `geo.py` where mypy fails to correctly infer return types of numpy ufuncs applied to xarray objects.
+- Change `AircraftPerformance` and downstream implementations for better support in running over `Fleet` sources. The runtime of `PSFlight` remains the same.
+
 ## v0.54.5
 
 ### Features

{pycontrails-0.54.5/pycontrails.egg-info → pycontrails-0.54.6}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: pycontrails
-Version: 0.54.5
+Version: 0.54.6
 Summary: Python library for modeling aviation climate impacts
 Author-email: Breakthrough Energy <py@contrails.org>
 License: Apache-2.0
@@ -49,8 +49,7 @@ Requires-Dist: pyarrow>=5.0; extra == "dev"
 Requires-Dist: pytest>=8.2; extra == "dev"
 Requires-Dist: pytest-cov>=2.11; extra == "dev"
 Requires-Dist: requests>=2.25; extra == "dev"
-Requires-Dist: ruff==0.8.0; extra == "dev"
-Requires-Dist: setuptools; extra == "dev"
+Requires-Dist: ruff>=0.9.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: doc8>=1.1; extra == "docs"
 Requires-Dist: furo>=2023.3; extra == "docs"

{pycontrails-0.54.5 → pycontrails-0.54.6}/docs/notebooks/ECMWF.ipynb

@@ -16,7 +16,7 @@
     "\n",
     "Support provided for:\n",
     "\n",
-    "- [ERA5](https://www.ecmwf.int/en/forecasts/dataset/ecmwf-reanalysis-v5) via the [Copernicus Data Store (CDS-Beta)](https://cds-beta.climate.copernicus.eu/) using [cdsapi](https://github.com/ecmwf/cdsapi) or user provided files\n",
+    "- [ERA5](https://www.ecmwf.int/en/forecasts/dataset/ecmwf-reanalysis-v5) via the [Copernicus Data Store](https://cds.climate.copernicus.eu/) using [cdsapi](https://github.com/ecmwf/cdsapi) or user provided files\n",
     "- [HRES](https://confluence.ecmwf.int/display/FUG/Section+2.1.1.2+Rationale+for+High+Resolution) and [ENS](https://confluence.ecmwf.int/display/FUG/Section+2.1.2.1+Medium+Range+Ensemble+forecasts) via [MARS](https://confluence.ecmwf.int/display/UDOC/MARS+user+documentation) using [ecmwf-api-client](https://github.com/ecmwf/ecmwf-api-client) or user provided files.\n",
     "\n",
     "For both ERA5 and HRES, we provide interfaces for accessing \"pressure-level data\" (fields pre-interpolated to a fixed set of pressure levels) or \"model-level data\" (fields retrieved on the native vertical grid and [interpolated after retrieval to an arbitrary set of pressure levels](model-levels.ipynb)). We recommend using model-level data when possible, as the resolution of pressure-level data is coarse relative to the vertical scale of ice-supersaturated regions.\n",
@@ -32,8 +32,8 @@
     "\n",
     "### Access\n",
     "\n",
-    "- Requires account with [Copernicus Data Portal](https://cds-beta.climate.copernicus.eu/)\n",
-    "- Provide `url` and `key` credentials on input, or refer to the [CDS API Documentation](https://cds-beta.climate.copernicus.eu/how-to-api) for how to create `~/.cdsapirc` file to configure access.\n",
+    "- Requires account with [Copernicus Data Portal](https://cds.climate.copernicus.eu/)\n",
+    "- Provide `url` and `key` credentials on input, or refer to the [CDS API Documentation](https://cds.climate.copernicus.eu/how-to-api) for how to create `~/.cdsapirc` file to configure access.\n",
     "\n",
     "### Reference\n",
     "\n",
@@ -87,7 +87,7 @@
     "    time=\"2022-03-01 00:00:00\",\n",
     "    variables=[\"t\", \"q\", \"u\", \"v\", \"w\", \"ciwc\", \"z\", \"cc\"],  # supports CF name or short names\n",
     "    pressure_levels=[200, 250, 300],\n",
-    "    # url=\"https://cds-beta.climate.copernicus.eu/api\",\n",
+    "    # url=\"https://cds.climate.copernicus.eu/api\",\n",
     "    # key=\"<key>\"\n",
     ")\n",
     "era5"
@@ -132,7 +132,7 @@
     "        \"cc\",\n",
     "    ],  # supports CF name or short names\n",
     "    pressure_levels=[300, 250, 200],\n",
-    "    # url=\"https://cds-beta.climate.copernicus.eu/api\",\n",
+    "    # url=\"https://cds.climate.copernicus.eu/api\",\n",
     "    # key=\"<key>\"\n",
     ")\n",
     "era5"
@@ -1429,7 +1429,7 @@
     "era5 = ERA5(\n",
     "    time=(\"2022-03-01 00:00:00\", \"2022-03-01 03:00:00\"),\n",
     "    variables=[\"tsr\", \"ttr\"],\n",
-    "    # url=\"https://cds-beta.climate.copernicus.eu/api\",\n",
+    "    # url=\"https://cds.climate.copernicus.eu/api\",\n",
     "    # key=\"<key>\"\n",
     ")\n",
     "era5"
@@ -6071,7 +6071,7 @@
     "    variables=variables,\n",
     "    pressure_levels=[300, 250, 150],\n",
     "    cachestore=gcp,\n",
-    "    # url=\"https://cds-beta.climate.copernicus.eu/api\",\n",
+    "    # url=\"https://cds.climate.copernicus.eu/api\",\n",
     "    # key=\"<key>\"\n",
     ")"
    ]

{pycontrails-0.54.5 → pycontrails-0.54.6}/pycontrails/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.54.5'
-__version_tuple__ = version_tuple = (0, 54, 5)
+__version__ = version = '0.54.6'
+__version_tuple__ = version_tuple = (0, 54, 6)

{pycontrails-0.54.5 → pycontrails-0.54.6}/pycontrails/core/aircraft_performance.py

@@ -96,22 +96,52 @@ class AircraftPerformance(Model):
 
     source: Flight
 
-    @abc.abstractmethod
     @overload
     def eval(self, source: Fleet, **params: Any) -> Fleet: ...
 
-    @abc.abstractmethod
     @overload
     def eval(self, source: Flight, **params: Any) -> Flight: ...
 
-    @abc.abstractmethod
     @overload
     def eval(self, source: None = ..., **params: Any) -> NoReturn: ...
 
-    @abc.abstractmethod
     def eval(self, source: Flight | None = None, **params: Any) -> Flight:
         """Evaluate the aircraft performance model.
 
+        Parameters
+        ----------
+        source : Flight
+            Flight trajectory to evaluate. Can be a :class:`Flight` or :class:`Fleet`.
+        params : Any
+            Override :attr:`params` with keyword arguments.
+
+        Returns
+        -------
+        Flight
+            Flight trajectory with aircraft performance data.
+        """
+        self.update_params(params)
+        self.set_source(source)
+        self.source = self.require_source_type(Flight)
+        self.downselect_met()
+        self.set_source_met()
+        self._cleanup_indices()
+
+        # Calculate true airspeed if not included on source
+        self.ensure_true_airspeed_on_source()
+
+        if isinstance(self.source, Fleet):
+            fls = [self.eval_flight(fl) for fl in self.source.to_flight_list()]
+            self.source = Fleet.from_seq(fls, attrs=self.source.attrs, broadcast_numeric=False)
+            return self.source
+
+        self.source = self.eval_flight(self.source)
+        return self.source
+
+    @abc.abstractmethod
+    def eval_flight(self, fl: Flight) -> Flight:
+        """Evaluate the aircraft performance model on a single flight trajectory.
+
         The implementing model adds the following fields to the source flight:
 
         - ``aircraft_mass``: aircraft mass at each waypoint, [:math:`kg`]
@@ -128,18 +158,6 @@ class AircraftPerformance(Model):
         - ``max_mach``: maximum Mach number
         - ``max_altitude``: maximum altitude, [:math:`m`]
         - ``total_fuel_burn``: total fuel burn, [:math:`kg`]
-
-        Parameters
-        ----------
-        source : Flight
-            Flight trajectory to evaluate.
-        params : Any
-            Override :attr:`params` with keyword arguments.
-
-        Returns
-        -------
-        Flight
-            Flight trajectory with aircraft performance data.
         """
 
     @override

{pycontrails-0.54.5 → pycontrails-0.54.6}/pycontrails/core/airports.py

@@ -162,7 +162,7 @@ def find_nearest_airport(
     ) & airports["latitude"].between((latitude - bbox), (latitude + bbox))
 
     # Find the nearest airport from largest to smallest airport type
-    search_priority = ["large_airport", "medium_airport", "small_airport"]
+    search_priority = ("large_airport", "medium_airport", "small_airport")
 
     for airport_type in search_priority:
         is_airport_type = airports["type"] == airport_type
@@ -171,7 +171,7 @@ def find_nearest_airport(
         if len(nearest_airports) == 1:
             return nearest_airports["icao_code"].values[0]
 
-        elif len(nearest_airports) > 1:
+        if len(nearest_airports) > 1:
             distance = distance_to_airports(
                 nearest_airports,
                 longitude,
@@ -181,8 +181,7 @@ def find_nearest_airport(
             i_nearest = np.argmin(distance)
             return nearest_airports["icao_code"].values[i_nearest]
 
-        else:
-            continue
+        continue
 
     return None
 

{pycontrails-0.54.5 → pycontrails-0.54.6}/pycontrails/core/flight.py

@@ -891,7 +891,7 @@ class Flight(GeoVectorDataset):
         """
         methods = "geodesic", "linear"
         if fill_method not in methods:
-            raise ValueError(f'Unknown `fill_method`. Supported  methods: {", ".join(methods)}')
+            raise ValueError(f"Unknown `fill_method`. Supported  methods: {', '.join(methods)}")
 
         # STEP 0: If self is empty, return an empty flight
         if not self:
@@ -1982,9 +1982,7 @@ def filter_altitude(
             result[i0:i1] = altitude_filt[i0:i1]
 
     # reapply Savitzky-Golay filter to smooth climb and descent
-    result = _sg_filter(result, window_length=kernel_size)
-
-    return result
+    return _sg_filter(result, window_length=kernel_size)
 
 
 def segment_duration(

{pycontrails-0.54.5 → pycontrails-0.54.6}/pycontrails/core/flightplan.py

@@ -21,24 +21,24 @@ def to_atc_plan(plan: dict[str, Any]) -> str:
     --------
     :func:`parse_atc_plan`
     """
-    ret = f'(FPL-{plan["callsign"]}-{plan["flight_rules"]}'
-    ret += f'{plan["type_of_flight"]}\n'
+    ret = f"(FPL-{plan['callsign']}-{plan['flight_rules']}"
+    ret += f"{plan['type_of_flight']}\n"
     ret += "-"
     if "number_aircraft" in plan and plan["number_aircraft"] <= 10:
         ret += plan["number_aircraft"]
-    ret += f'{plan["type_of_aircraft"]}/{plan["wake_category"]}-'
-    ret += f'{plan["equipment"]}/{plan["transponder"]}\n'
-    ret += f'-{plan["departure_icao"]}{plan["time"]}\n'
-    ret += f'-{plan["speed_type"]}{plan["speed"]}{plan["level_type"]}'
-    ret += f'{plan["level"]} {plan["route"]}\n'
+    ret += f"{plan['type_of_aircraft']}/{plan['wake_category']}-"
+    ret += f"{plan['equipment']}/{plan['transponder']}\n"
+    ret += f"-{plan['departure_icao']}{plan['time']}\n"
+    ret += f"-{plan['speed_type']}{plan['speed']}{plan['level_type']}"
+    ret += f"{plan['level']} {plan['route']}\n"
     if "destination_icao" in plan and "duration" in plan:
-        ret += f'-{plan["destination_icao"]}{plan["duration"]}'
+        ret += f"-{plan['destination_icao']}{plan['duration']}"
     if "alt_icao" in plan:
-        ret += f' {plan["alt_icao"]}'
+        ret += f" {plan['alt_icao']}"
     if "second_alt_icao" in plan:
-        ret += f' {plan["second_alt_icao"]}'
+        ret += f" {plan['second_alt_icao']}"
     ret += "\n"
-    ret += f'-{plan["other_info"]})\n'
+    ret += f"-{plan['other_info']})\n"
     if "supplementary_info" in plan:
         ret += " ".join([f"{i[0]}/{i[1]}" for i in plan["supplementary_info"].items()])
 

{pycontrails-0.54.5 → pycontrails-0.54.6}/pycontrails/core/met_var.py

@@ -282,6 +282,35 @@ VerticalVelocity = MetVariable(
     ),
 )
 
+MassFractionOfCloudLiquidWaterInAir = MetVariable(
+    short_name="clw",
+    standard_name="mass_fraction_of_cloud_liquid_water_in_air",
+    long_name="Mass fraction of cloud liquid water in air",
+    units="kg kg**-1",
+    level_type="isobaricInhPa",
+    amip="clw",
+    description=("The mass fraction of cloud liquid water in moist air."),
+)
+
+MassFractionOfCloudIceInAir = MetVariable(
+    short_name="cli",
+    standard_name="mass_fraction_of_cloud_ice_in_air",
+    long_name="Mass fraction of cloud ice in air",
+    units="kg kg**-1",
+    level_type="isobaricInhPa",
+    amip="cli",
+    description=("The mass fraction of cloud ice in moist air."),
+)
+
+CloudAreaFractionInAtmosphereLayer = MetVariable(
+    short_name="cl",
+    standard_name="cloud_area_fraction_in_atmosphere_layer",
+    long_name="Cloud area fraction in atmosphere layer",
+    units="[0 - 1]",
+    level_type="isobaricInhPa",
+    description=("The fraction of the horizontal area of a grid cell that contains cloud."),
+)
+
 
 # ----
 # Single level variables
@@ -305,3 +334,36 @@ SurfacePressure = MetVariable(
         "Earth's surface represented at a fixed point."
     ),
 )
+
+TOANetDownwardShortwaveFlux = MetVariable(
+    short_name="rst",
+    standard_name="toa_net_downward_shortwave_flux",
+    long_name="TOA net downward shortwave flux",
+    units="W m**-2",
+    level_type="nominalTop",
+    amip="rst",
+    description=(
+        '"shortwave" means shortwave radiation. "toa" means top of atmosphere. '
+        '"Downward" indicates a vector component which is positive when directed '
+        "downward (negative upward). Net downward radiation is the difference "
+        "between radiation from above (downwelling) and radiation from below (upwelling). "
+        "In accordance with common usage in geophysical disciplines, "
+        '"flux" implies per unit area, called "flux density" in physics.'
+    ),
+)
+
+TOAOutgoingLongwaveFlux = MetVariable(
+    short_name="rlut",
+    standard_name="toa_outgoing_longwave_flux",
+    long_name="TOA outgoing longwave_flux",
+    units="W m**-2",
+    level_type="nominalTop",
+    amip="rlut",
+    description=(
+        '"longwave" means longwave radiation. "toa" means top of atmosphere. '
+        "The TOA outgoing longwave flux is the upwelling thermal radiative flux, "
+        'often called the "outgoing longwave radiation" or "OLR". '
+        "In accordance with common usage in geophysical disciplines, "
+        '"flux" implies per unit area, called "flux density" in physics.'
+    ),
+)

{pycontrails-0.54.5 → pycontrails-0.54.6}/pycontrails/core/models.py

@@ -986,6 +986,7 @@ def _prepare_q(
         return _prepare_q_cubic_spline(da, level)
 
     raise_invalid_q_method_error(q_method)
+    return None
 
 
 def _prepare_q_log_q_log_p(