pycontrails 0.54.1__cp313-cp313-win_amd64.whl → 0.54.3__cp313-cp313-win_amd64.whl

pycontrails/models/dry_advection.py

@@ -9,7 +9,6 @@ import numpy as np
 import numpy.typing as npt
 
 from pycontrails.core import models
-from pycontrails.core.flight import Flight
 from pycontrails.core.met import MetDataset
 from pycontrails.core.met_var import AirTemperature, EastwardWind, NorthwardWind, VerticalVelocity
 from pycontrails.core.vector import GeoVectorDataset
@@ -92,9 +91,6 @@ class DryAdvection(models.Model):
     met_required = True
     source: GeoVectorDataset
 
-    @overload
-    def eval(self, source: Flight, **params: Any) -> Flight: ...
-
     @overload
     def eval(self, source: GeoVectorDataset, **params: Any) -> GeoVectorDataset: ...
 
@@ -109,7 +105,12 @@ class DryAdvection(models.Model):
         Parameters
         ----------
         source : GeoVectorDataset
-            Arbitrary points to advect.
+            Arbitrary points to advect. A :class:`Flight` instance is not treated any
+            differently than a :class:`GeoVectorDataset`. In particular, the user must
+            explicitly set ``flight["azimuth"] = flight.segment_azimuth()`` if they
+            want to use wind shear effects for a flight.
+            In the current implementation, any existing meteorological variables in the ``source``
+            are ignored. The ``source`` will be interpolated against the :attr:`met` dataset.
         params : Any
             Overwrite model parameters defined in ``__init__``.
 
@@ -122,7 +123,7 @@ class DryAdvection(models.Model):
         self.set_source(source)
         self.source = self.require_source_type(GeoVectorDataset)
 
-        self._prepare_source()
+        self.source = self._prepare_source()
 
         interp_kwargs = self.interp_kwargs
 
@@ -142,7 +143,7 @@ class DryAdvection(models.Model):
         evolved = []
         for t in timesteps:
             filt = (source_time < t) & (source_time >= t - dt_integration)
-            vector = self.source.filter(filt) + vector
+            vector = self.source.filter(filt, copy=False) + vector
             vector = _evolve_one_step(
                 self.met,
                 vector,
@@ -162,49 +163,44 @@ class DryAdvection(models.Model):
 
         return GeoVectorDataset.sum(evolved, fill_value=np.nan)
 
-    def _prepare_source(self) -> None:
+    def _prepare_source(self) -> GeoVectorDataset:
         r"""Prepare :attr:`source` vector for advection by wind-shear-derived variables.
 
-        This method adds the following variables to :attr:`source` if the `"azimuth"`
-        parameter is not None:
+        The following variables are always guaranteed to be present in :attr:`source`:
 
         - ``age``: Age of plume.
+        - ``waypoint``: Identifier for each waypoint.
+
+        If `"azimuth"` is present in :attr:`source`, `source.attrs`, or :attr:`params`,
+        the following variables will also be added:
+
         - ``azimuth``: Initial plume direction, measured in clockwise direction from
-          true north, [:math:`\deg`].
+            true north, [:math:`\deg`].
         - ``width``: Initial plume width, [:math:`m`].
         - ``depth``: Initial plume depth, [:math:`m`].
         - ``sigma_yz``: All zeros for cross-term term in covariance matrix of plume.
-        """
 
+        Returns
+        -------
+        GeoVectorDataset
+            A filtered version of the source with only the required columns.
+        """
         self.source.setdefault("level", self.source.level)
-
-        columns: tuple[str, ...] = ("longitude", "latitude", "level", "time")
-        if "azimuth" in self.source:
-            columns += ("azimuth",)
-        self.source = GeoVectorDataset(self.source.select(columns, copy=False))
-
-        # Get waypoint index if not already set
+        self.source["age"] = np.full(self.source.size, np.timedelta64(0, "ns"))
         self.source.setdefault("waypoint", np.arange(self.source.size))
 
-        self.source["age"] = np.full(self.source.size, np.timedelta64(0, "ns"))
+        columns = ["longitude", "latitude", "level", "time", "age", "waypoint"]
+        azimuth = self.get_source_param("azimuth", set_attr=False)
+        if azimuth is None:
+            # Early exit for pointwise only simulation
+            if self.params["width"] is not None or self.params["depth"] is not None:
+                raise ValueError(
+                    "If 'azimuth' is None, then 'width' and 'depth' must also be None."
+                )
+            return GeoVectorDataset(self.source.select(columns, copy=False), copy=False)
 
         if "azimuth" not in self.source:
-            if isinstance(self.source, Flight):
-                pointwise_only = False
-                self.source["azimuth"] = self.source.segment_azimuth()
-            else:
-                try:
-                    self.source.broadcast_attrs("azimuth")
-                except KeyError:
-                    if (azimuth := self.params["azimuth"]) is not None:
-                        pointwise_only = False
-                        self.source["azimuth"] = np.full_like(self.source["longitude"], azimuth)
-                    else:
-                        pointwise_only = True
-                else:
-                    pointwise_only = False
-        else:
-            pointwise_only = False
+            self.source["azimuth"] = np.full_like(self.source["longitude"], azimuth)
 
         for key in ("width", "depth"):
             if key in self.source:
@@ -214,18 +210,12 @@ class DryAdvection(models.Model):
                 continue
 
             val = self.params[key]
-            if val is None and not pointwise_only:
+            if val is None:
                 raise ValueError(f"If '{key}' is None, then 'azimuth' must also be None.")
 
-            if val is not None and pointwise_only:
-                raise ValueError(f"Cannot specify '{key}' without specifying 'azimuth'.")
-
-            if not pointwise_only:
-                self.source[key] = np.full_like(self.source["longitude"], val)
-
-        if pointwise_only:
-            return
+            self.source[key] = np.full_like(self.source["longitude"], val)
 
+        columns.extend(["azimuth", "width", "depth", "sigma_yz", "area_eff"])
         self.source["sigma_yz"] = np.zeros_like(self.source["longitude"])
         width = self.source["width"]
         depth = self.source["depth"]
@@ -233,6 +223,8 @@ class DryAdvection(models.Model):
             width, depth, sigma_yz=0.0
         )
 
+        return GeoVectorDataset(self.source.select(columns, copy=False), copy=False)
+
 
 def _perform_interp_for_step(
     met: MetDataset,
@@ -412,15 +404,20 @@ def _calc_geometry(
     u_wind_tail = vector.data.pop("eastward_wind_tail")
     v_wind_tail = vector.data.pop("northward_wind_tail")
 
-    longitude_head_t2 = geo.advect_longitude(
-        longitude=longitude_head, latitude=latitude_head, u_wind=u_wind_head, dt=dt
+    longitude_head_t2, latitude_head_t2 = geo.advect_horizontal(
+        longitude=longitude_head,
+        latitude=latitude_head,
+        u_wind=u_wind_head,
+        v_wind=v_wind_head,
+        dt=dt,
     )
-    latitude_head_t2 = geo.advect_latitude(latitude=latitude_head, v_wind=v_wind_head, dt=dt)
-
-    longitude_tail_t2 = geo.advect_longitude(
-        longitude=longitude_tail, latitude=latitude_tail, u_wind=u_wind_tail, dt=dt
+    longitude_tail_t2, latitude_tail_t2 = geo.advect_horizontal(
+        longitude=longitude_tail,
+        latitude=latitude_tail,
+        u_wind=u_wind_tail,
+        v_wind=v_wind_tail,
+        dt=dt,
     )
-    latitude_tail_t2 = geo.advect_latitude(latitude=latitude_tail, v_wind=v_wind_tail, dt=dt)
 
     azimuth_2 = geo.azimuth(
         lons0=longitude_tail_t2,
@@ -453,8 +450,7 @@ def _evolve_one_step(
     longitude = vector["longitude"]
 
     dt = t - vector["time"]
-    longitude_2 = geo.advect_longitude(longitude, latitude, u_wind, dt)  # type: ignore[arg-type]
-    latitude_2 = geo.advect_latitude(latitude, v_wind, dt)  # type: ignore[arg-type]
+    longitude_2, latitude_2 = geo.advect_horizontal(longitude, latitude, u_wind, v_wind, dt)  # type: ignore[arg-type]
     level_2 = geo.advect_level(
         vector.level,
         vertical_velocity,

pycontrails/models/humidity_scaling/humidity_scaling.py

@@ -7,14 +7,19 @@ import contextlib
 import dataclasses
 import functools
 import pathlib
+import sys
 import warnings
 from typing import Any, NoReturn, overload
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
 import xarray as xr
-from overrides import overrides
 
 from pycontrails.core import models
 from pycontrails.core.met import MetDataArray, MetDataset
@@ -202,7 +207,7 @@ class ConstantHumidityScaling(HumidityScaling):
     default_params = ConstantHumidityScalingParams
     scaler_specific_keys = ("rhi_adj",)
 
-    @overrides
+    @override
     def scale(
         self,
         specific_humidity: ArrayLike,
@@ -254,7 +259,7 @@ class ExponentialBoostHumidityScaling(HumidityScaling):
     default_params = ExponentialBoostHumidityScalingParams
     scaler_specific_keys = "rhi_adj", "rhi_boost_exponent", "clip_upper"
 
-    @overrides
+    @override
     def scale(
         self,
         specific_humidity: ArrayLike,
@@ -408,7 +413,7 @@ class ExponentialBoostLatitudeCorrectionHumidityScaling(HumidityScaling):
         q_method = self.params["interpolation_q_method"]
         return {**super()._scale_kwargs(), "q_method": q_method}
 
-    @overrides
+    @override
     def scale(
         self,
         specific_humidity: ArrayLike,
@@ -557,7 +562,7 @@ class HumidityScalingByLevel(HumidityScaling):
         "stratosphere_threshold",
     )
 
-    @overrides
+    @override
     def scale(
         self,
         specific_humidity: ArrayLike,
@@ -825,7 +830,7 @@ class HistogramMatching(HumidityScaling):
             warnings.warn(msg, DeprecationWarning)
         super().__init__(met, params, **params_kwargs)
 
-    @overrides
+    @override
     def scale(
         self,
         specific_humidity: ArrayLike,
@@ -976,7 +981,7 @@ class HistogramMatchingWithEckel(HumidityScaling):
 
         return self.source
 
-    @overrides
+    @override
     def scale(  # type: ignore[override]
         self,
         specific_humidity: npt.NDArray[np.float64],

pycontrails/models/ps_model/__init__.py

@@ -4,7 +4,7 @@ from pycontrails.models.ps_model.ps_aircraft_params import (
     PSAircraftEngineParams,
     load_aircraft_engine_params,
 )
-from pycontrails.models.ps_model.ps_grid import PSGrid, ps_nominal_grid
+from pycontrails.models.ps_model.ps_grid import PSGrid, ps_nominal_grid, ps_nominal_optimize_mach
 from pycontrails.models.ps_model.ps_model import PSFlight, PSFlightParams
 
 __all__ = [
@@ -14,4 +14,5 @@ __all__ = [
     "PSGrid",
     "load_aircraft_engine_params",
     "ps_nominal_grid",
+    "ps_nominal_optimize_mach",
 ]

pycontrails/models/ps_model/ps_aircraft_params.py

@@ -11,6 +11,7 @@ from typing import Any
 import numpy as np
 import pandas as pd
 
+from pycontrails.core.aircraft_performance import AircraftPerformanceParams
 from pycontrails.physics import constants as c
 
 #: Path to the Poll-Schumann aircraft parameters CSV file.
@@ -193,7 +194,7 @@ def _row_to_aircraft_engine_params(tup: Any) -> tuple[str, PSAircraftEngineParam
 
 @functools.cache
 def load_aircraft_engine_params(
-    engine_deterioration_factor: float = 0.025,
+    engine_deterioration_factor: float = AircraftPerformanceParams.engine_deterioration_factor,
 ) -> Mapping[str, PSAircraftEngineParams]:
     """
     Extract aircraft-engine parameters for each aircraft type supported by the PS model.
@@ -254,7 +255,7 @@ def load_aircraft_engine_params(
     }
 
     df = pd.read_csv(PS_FILE_PATH, dtype=dtypes)
-    df["eta_1"] = df["eta_1"] * (1.0 - engine_deterioration_factor)
+    df["eta_1"] *= 1.0 - engine_deterioration_factor
 
     return dict(_row_to_aircraft_engine_params(tup) for tup in df.itertuples(index=False))
 

pycontrails/models/ps_model/ps_grid.py

@@ -333,6 +333,7 @@ def ps_nominal_grid(
     q_fuel: float = JetA.q_fuel,
     mach_number: float | None = None,
     maxiter: int = PSGridParams.maxiter,
+    engine_deterioration_factor: float = PSGridParams.engine_deterioration_factor,
 ) -> xr.Dataset:
     """Calculate the nominal performance grid for a given aircraft type.
 
@@ -359,6 +360,9 @@ def ps_nominal_grid(
         The Mach number. If None (default), the PS design Mach number is used.
     maxiter : int, optional
         Passed into :func:`scipy.optimize.newton`.
+    engine_deterioration_factor : float, optional
+        The engine deterioration factor,
+        by default :attr:`PSGridParams.engine_deterioration_factor`.
 
     Returns
     -------
@@ -428,7 +432,7 @@ def ps_nominal_grid(
 
     air_pressure = level * 100.0
 
-    aircraft_engine_params = ps_model.load_aircraft_engine_params()
+    aircraft_engine_params = ps_model.load_aircraft_engine_params(engine_deterioration_factor)
 
     try:
         atyp_param = aircraft_engine_params[aircraft_type]
@@ -503,3 +507,185 @@ def ps_nominal_grid(
         coords=coords,
         attrs=attrs,
     )
+
+
+def _newton_mach(
+    mach_number: ArrayOrFloat,
+    perf: _PerfVariables,
+    aircraft_mass: ArrayOrFloat,
+    headwind: ArrayOrFloat,
+    cost_index: ArrayOrFloat,
+) -> ArrayOrFloat:
+    """Approximate the derivative of the cost of a segment based on mach number.
+
+    This is used to find the mach number at which cost in minimized.
+    """
+    perf.mach_number = mach_number + 1e-4
+    tas = units.mach_number_to_tas(perf.mach_number, perf.air_temperature)
+    groundspeed = tas - headwind
+    ff1 = _nominal_perf(aircraft_mass, perf).fuel_flow
+    eccf1 = (cost_index + ff1 * 60) / groundspeed
+
+    perf.mach_number = mach_number - 1e-4
+    tas = units.mach_number_to_tas(perf.mach_number, perf.air_temperature)
+    groundspeed = tas - headwind
+    ff2 = _nominal_perf(aircraft_mass, perf).fuel_flow
+    eccf2 = (cost_index + ff2 * 60) / groundspeed
+    return eccf1 - eccf2
+
+
+def ps_nominal_optimize_mach(
+    aircraft_type: str,
+    aircraft_mass: ArrayOrFloat,
+    cost_index: ArrayOrFloat,
+    level: ArrayOrFloat,
+    *,
+    air_temperature: ArrayOrFloat | None = None,
+    northward_wind: ArrayOrFloat | None = None,
+    eastward_wind: ArrayOrFloat | None = None,
+    sin_a: ArrayOrFloat | None = None,
+    cos_a: ArrayOrFloat | None = None,
+    q_fuel: float = JetA.q_fuel,
+    engine_deterioration_factor: float = PSGridParams.engine_deterioration_factor,
+) -> xr.Dataset:
+    """Calculate the nominal optimal mach number for a given aircraft type.
+
+    This function is similar to the :class:`ps_nominal_grid` method, but rather than
+    maximizing engine efficiecy by adjusting aircraft, we are minimizing cost by adjusting
+    mach number.
+
+    Parameters
+    ----------
+    aircraft_type : str
+        The aircraft type.
+    aircraft_mass: ArrayOrFloat
+        The aircraft mass, [:math:`kg`].
+    cost_index: ArrayOrFloat
+        The cost index, [:math:`kg/min`], or non-fuel cost of one minute of flight time
+    level : ArrayOrFloat
+        The pressure level, [:math:`hPa`]. If a :class:`numpy.ndarray` is passed, it is
+        assumed to be one dimensional and the same length as the``aircraft_mass`` argument.
+    air_temperature : ArrayOrFloat | None, optional
+        The ambient air temperature, [:math:`K`]. If None (default), the ISA
+        temperature is computed from the ``level`` argument. If a :class:`numpy.ndarray`
+        is passed, it is assumed to be one dimensional and the same length as the
+        ``aircraft_mass`` argument.
+    air_temperature : ArrayOrFloat | None, optional
+    northward_wind: ArrayOrFloat | None = None, optional
+        The northward component of winds, [:math:`m/s`]. If None (default) assumed to be
+        zero.
+    eastward_wind: ArrayOrFloat | None = None, optional
+        The eastward component of winds, [:math:`m/s`]. If None (default) assumed to be
+        zero.
+    sin_a: ArrayOrFloat | None = None, optional
+        The sine between the true bearing of flight and the longitudinal axis. Must be
+        specified if wind data is provided. Will be ignored if wind data is not provided.
+    cos_a: ArrayOrFloat | None = None, optional
+        The cosine between the true bearing of flight and the longitudinal axis. Must be
+        specified if wind data is provided. Will be ignored if wind data is not provided.
+    q_fuel : float, optional
+        The fuel heating value, by default :attr:`JetA.q_fuel`.
+    engine_deterioration_factor : float, optional
+        The engine deterioration factor,
+        by default :attr:`PSGridParams.engine_deterioration_factor`.
+
+    Returns
+    -------
+    xr.Dataset
+        The nominal performance grid. The grid is indexed by altitude.
+        Contains the following variables:
+
+        - ``"mach_number"``: The mach number that minimizes segment cost
+        - ``"fuel_flow"`` : Fuel flow rate, [:math:`kg/s`]
+        - ``"engine_efficiency"`` : Engine efficiency
+        - ``"aircraft_mass"`` : Aircraft mass,
+          [:math:`kg`]
+
+    Raises
+    ------
+    KeyError
+        If "aircraft_type" is not supported by the PS model.
+    ValueError
+        If wind data is provided without segment angles.
+    """
+    dims = ("level",)
+    coords = {"level": level}
+    aircraft_engine_params = ps_model.load_aircraft_engine_params(engine_deterioration_factor)
+    try:
+        atyp_param = aircraft_engine_params[aircraft_type]
+    except KeyError as exc:
+        msg = (
+            f"The aircraft type {aircraft_type} is not currently supported by the PS model. "
+            f"Available aircraft types are: {list(aircraft_engine_params)}"
+        )
+        raise KeyError(msg) from exc
+
+    if air_temperature is None:
+        altitude_m = units.pl_to_m(level)
+        air_temperature = units.m_to_T_isa(altitude_m)
+
+    headwind: ArrayOrFloat
+    if northward_wind is not None and eastward_wind is not None:
+        if sin_a is None or cos_a is None:
+            msg = "Segment angles must be provide if wind data is specified"
+            raise ValueError(msg)
+        headwind = -(northward_wind * cos_a + eastward_wind * sin_a)
+    else:
+        headwind = 0.0  # type: ignore
+
+    min_mach = ps_operational_limits.minimum_mach_num(
+        air_pressure=level * 100.0,
+        aircraft_mass=aircraft_mass,
+        atyp_param=atyp_param,
+    )
+
+    max_mach = ps_operational_limits.maximum_mach_num(
+        altitude_ft=units.pl_to_ft(level),
+        air_pressure=level * 100.0,
+        aircraft_mass=aircraft_mass,
+        air_temperature=air_temperature,
+        theta=np.full_like(aircraft_mass, 0.0),
+        atyp_param=atyp_param,
+    )
+
+    x0 = (min_mach + max_mach) / 2.0  # type: ignore
+
+    perf = _PerfVariables(
+        atyp_param=atyp_param,
+        air_pressure=level * 100.0,
+        air_temperature=air_temperature,
+        mach_number=x0,
+        q_fuel=q_fuel,
+    )
+
+    opt_mach = scipy.optimize.newton(
+        func=_newton_mach,
+        args=(perf, aircraft_mass, headwind, cost_index),
+        x0=x0,
+        tol=1e-4,
+        disp=False,
+    ).clip(min=min_mach, max=max_mach)
+
+    perf.mach_number = opt_mach
+    output = _nominal_perf(aircraft_mass, perf)
+
+    engine_efficiency = output.engine_efficiency
+    fuel_flow = output.fuel_flow
+
+    attrs = {
+        "aircraft_type": aircraft_type,
+        "q_fuel": q_fuel,
+        "wingspan": atyp_param.wing_span,
+        "n_engine": atyp_param.n_engine,
+    }
+
+    return xr.Dataset(
+        {
+            "mach_number": (dims, opt_mach),
+            "aircraft_mass": (dims, aircraft_mass),
+            "engine_efficiency": (dims, engine_efficiency),
+            "fuel_flow": (dims, fuel_flow),
+        },
+        coords=coords,
+        attrs=attrs,
+    )

pycontrails/models/ps_model/ps_model.py

@@ -5,13 +5,18 @@ from __future__ import annotations
 import dataclasses
 import functools
 import pathlib
+import sys
 from collections.abc import Mapping
 from typing import Any, NoReturn, overload
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
-from overrides import overrides
 
 from pycontrails.core import flight
 from pycontrails.core.aircraft_performance import (
@@ -46,13 +51,6 @@ class PSFlightParams(AircraftPerformanceParams):
     #: efficiency to always exceed this value.
     eta_over_eta_b_min: float | None = 0.5
 
-    #: Account for "in-service" engine deterioration between maintenance cycles.
-    #: Default value is set to +2.5% increase in fuel consumption.
-    # Reference:
-    # Gurrola Arrieta, M.D.J., Botez, R.M. and Lasne, A., 2024. An Engine Deterioration Model for
-    # Predicting Fuel Consumption Impact in a Regional Aircraft. Aerospace, 11(6), p.426.
-    engine_deterioration_factor: float = 0.025
-
 
 class PSFlight(AircraftPerformance):
     """Simulate aircraft performance using Poll-Schumann (PS) model.
@@ -65,6 +63,10 @@ class PSFlight(AircraftPerformance):
     Poll & Schumann (2022). An estimation method for the fuel burn and other performance
     characteristics of civil transport aircraft. Part 3 Generalisation to cover climb,
     descent and holding. Aero. J., submitted.
+
+    See Also
+    --------
+    pycontrails.physics.jet.aircraft_load_factor
     """
 
     name = "PSFlight"
@@ -125,7 +127,7 @@ class PSFlight(AircraftPerformance):
     @overload
     def eval(self, source: None = ..., **params: Any) -> NoReturn: ...
 
-    @overrides
+    @override
     def eval(self, source: Flight | None = None, **params: Any) -> Flight:
         self.update_params(params)
         self.set_source(source)
@@ -217,7 +219,7 @@ class PSFlight(AircraftPerformance):
 
         return fl
 
-    @overrides
+    @override
     def calculate_aircraft_performance(
         self,
         *,