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

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

@@ -51,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.
@@ -70,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"

pycontrails/models/ps_model/ps_operational_limits.py

@@ -350,49 +350,47 @@ def max_usable_lift_coefficient(
 
 
 def minimum_mach_num(
-    air_pressure: float,
-    aircraft_mass: float,
+    air_pressure: ArrayOrFloat,
+    aircraft_mass: ArrayOrFloat,
     atyp_param: PSAircraftEngineParams,
-) -> float:
+) -> ArrayOrFloat:
     """
     Calculate minimum mach number to avoid stall.
 
     Parameters
     ----------
-    air_pressure : float
+    air_pressure : ArrayOrFloat
         Ambient pressure, [:math:`Pa`]
-    aircraft_mass : float
+    aircraft_mass : ArrayOrFloat
         Aircraft mass at each waypoint, [:math:`kg`]
     atyp_param : PSAircraftEngineParams
         Extracted aircraft and engine parameters.
 
     Returns
     -------
-    float
-        Maximum usable lift coefficient.
+    ArrayOrFloat
+        Minimum mach number to avoid stall.
     """
 
     def excess_mass(
-        mach_number: float,
-        air_pressure: float,
-        aircraft_mass: float,
+        mach_number: ArrayOrFloat,
+        air_pressure: ArrayOrFloat,
+        aircraft_mass: ArrayOrFloat,
         mach_num_des: float,
         c_l_do: float,
         wing_surface_area: float,
-    ) -> float:
+    ) -> ArrayOrFloat:
         amass_max = max_allowable_aircraft_mass(
             air_pressure,
             mach_number,
             mach_num_des,
             c_l_do,
             wing_surface_area,
-            1e10,
+            1e10,  # clipped to this value which we want to ignore
         )
-        if amass_max < 0:
-            return np.nan
         return amass_max - aircraft_mass
 
-    m = scipy.optimize.root_scalar(
+    m = scipy.optimize.newton(
         excess_mass,
         args=(
             air_pressure,
@@ -401,21 +399,22 @@ def minimum_mach_num(
             atyp_param.c_l_do,
             atyp_param.wing_surface_area,
         ),
-        x0=0.5,
-        x1=0.6,
-    ).root
+        x0=np.full_like(air_pressure, 0.4),
+        x1=np.full_like(air_pressure, 0.5),
+        tol=1e-4,
+    )
 
     return m
 
 
 def maximum_mach_num(
-    altitude_ft: float,
-    air_pressure: float,
-    aircraft_mass: float,
-    air_temperature: float,
-    theta: float,
+    altitude_ft: ArrayOrFloat,
+    air_pressure: ArrayOrFloat,
+    aircraft_mass: ArrayOrFloat,
+    air_temperature: ArrayOrFloat,
+    theta: ArrayOrFloat,
     atyp_param: PSAircraftEngineParams,
-) -> float:
+) -> ArrayOrFloat:
     r"""
     Return the maximum mach number at the current operating conditions.
 
@@ -424,23 +423,23 @@ def maximum_mach_num(
 
     Parameters
     ----------
-    altitude_ft  : float
+    altitude_ft  : ArrayOrFloat
         Altitude, [:math:`ft`]
-    air_pressure : float
+    air_pressure : ArrayOrFloat
         Ambient pressure, [:math:`Pa`]
-    aircraft_mass : float
+    aircraft_mass : ArrayOrFloat
         Aircraft mass at each waypoint, [:math:`kg`]
-    air_temperature : npt.NDArray[np.float64]
+    air_temperature : ArrayOrFloat
         Array of ambient temperature, [:math: `K`]
-    theta : float | npt.NDArray[np.float64]
+    theta : ArrayOrFloat
         Climb (positive value) or descent (negative value) angle, [:math:`\deg`]
     atyp_param : PSAircraftEngineParams
         Extracted aircraft and engine parameters.
 
     Returns
     -------
-    float
-        Maximum usable lift coefficient.
+    ArrayOrFloat
+        Maximum mach number given thrust limiations.
     """
     # Max speed ignoring thrust limits
     mach_num_op_lim = max_mach_number_by_altitude(
@@ -451,27 +450,15 @@ def maximum_mach_num(
         atyp_param.p_inf_co,
     )
 
-    # If the max mach number ignoring thrust limits is possible, return that value
-    if (
-        get_excess_thrust_available(
-            mach_num_op_lim, air_temperature, air_pressure, aircraft_mass, theta, atyp_param
-        )
-        > 0
-    ):
-        return mach_num_op_lim
-
-    # Numerically solve for the speed where drag == max thrust
-    try:
-        m_max = scipy.optimize.root_scalar(
-            get_excess_thrust_available,
-            args=(air_temperature, air_pressure, aircraft_mass, theta, atyp_param),
-            x0=mach_num_op_lim,
-            x1=mach_num_op_lim - 0.05,
-        ).root
-    except ValueError:
-        return np.nan
-
-    return m_max
+    max_mach = scipy.optimize.newton(
+        func=get_excess_thrust_available,
+        args=(air_temperature, air_pressure, aircraft_mass, theta, atyp_param),
+        x0=mach_num_op_lim,
+        x1=mach_num_op_lim - 0.01,
+        tol=1e-4,
+    ).clip(max=mach_num_op_lim)
+
+    return max_mach
 
 
 # ----------------

pycontrails/physics/geo.py

@@ -855,6 +855,155 @@ def advect_level(
     return (level * 100.0 + (dt_s * dp_dt)) / 100.0
 
 
+def advect_longitude_and_latitude_near_poles(
+    longitude: npt.NDArray[np.floating],
+    latitude: npt.NDArray[np.floating],
+    u_wind: npt.NDArray[np.floating],
+    v_wind: npt.NDArray[np.floating],
+    dt: npt.NDArray[np.timedelta64] | np.timedelta64,
+) -> tuple[npt.NDArray[np.floating], npt.NDArray[np.floating]]:
+    r"""Advect a particle near the poles.
+
+    This function calculates the longitude and latitude of a particle after time ``dt``
+    caused by advection due to wind near the poles (above 80 degrees North and South).
+
+    Automatically wrap over the antimeridian if necessary.
+
+    Parameters
+    ----------
+    longitude : npt.NDArray[np.floating]
+        Original longitude, [:math:`\deg`]
+    latitude : npt.NDArray[np.floating]
+        Original latitude, [:math:`\deg`]
+    u_wind : npt.NDArray[np.floating]
+        Wind speed in the longitudinal direction, [:math:`m s^{-1}`]
+    v_wind : npt.NDArray[np.floating]
+        Wind speed in the latitudinal direction, [:math:`m s^{-1}`]
+    dt : npt.NDArray[np.timedelta64] | np.timedelta64
+        Advection timestep
+
+    Returns
+    -------
+    tuple[npt.NDArray[np.floating], npt.NDArray[np.floating]]
+        New longitude and latitude values, [:math:`\deg`]
+
+    Notes
+    -----
+    Near the poles, the longitude and latitude is converted to a 2-D Cartesian-like coordinate
+    system to avoid numerical instabilities and singularities caused by convergence of meridians.
+
+    See Also
+    --------
+    advect_longitude
+    advect_latitude
+    advect_horizontal
+    """
+    # Determine hemisphere sign (1 for Northern Hemisphere, -1 for Southern Hemisphere)
+    hemisphere_sign = np.where(latitude > 0.0, 1.0, -1.0)
+
+    # Convert longitude and latitude to radians
+    sin_lon_rad = np.sin(units.degrees_to_radians(longitude))
+    cos_lon_rad = np.cos(units.degrees_to_radians(longitude))
+
+    # Convert longitude and latitude to 2-D Cartesian-like coordinate system, [:math:`\deg`]
+    polar_radius = 90.0 - np.abs(latitude)
+    x_cartesian = sin_lon_rad * polar_radius
+    y_cartesian = -cos_lon_rad * polar_radius * hemisphere_sign
+
+    # Convert winds from eastward and northward direction (u, v) to (X, Y), [:math:`\deg s^{-1}`]
+    x_wind = units.radians_to_degrees(
+        (u_wind * cos_lon_rad - v_wind * sin_lon_rad * hemisphere_sign) / constants.radius_earth
+    )
+    y_wind = units.radians_to_degrees(
+        (u_wind * sin_lon_rad * hemisphere_sign + v_wind * cos_lon_rad) / constants.radius_earth
+    )
+
+    # Advect contrails in 2-D Cartesian-like plane, [:math:`\deg`]
+    dtype = np.result_type(latitude, v_wind)
+    dt_s = units.dt_to_seconds(dt, dtype)
+    x_cartesian_new = x_cartesian + dt_s * x_wind
+    y_cartesian_new = y_cartesian + dt_s * y_wind
+
+    # Convert `y_cartesian_new` back to `latitude`, [:math:`\deg`]
+    dist_squared = x_cartesian_new**2 + y_cartesian_new**2
+    new_latitude = (90.0 - np.sqrt(dist_squared)) * hemisphere_sign
+
+    # Convert `x_cartesian_new` back to `longitude`, [:math:`\deg`]
+    new_lon_rad = np.arctan2(y_cartesian_new, x_cartesian_new)
+
+    new_longitude = np.where(
+        (x_wind == 0.0) & (y_wind == 0.0),
+        longitude,
+        90.0 + units.radians_to_degrees(new_lon_rad) * hemisphere_sign,
+    )
+    # new_longitude = 90.0 + units.radians_to_degrees(new_lon_rad) * hemisphere_sign
+    new_longitude = (new_longitude + 180.0) % 360.0 - 180.0  # wrap antimeridian
+    return new_longitude, new_latitude
+
+
+def advect_horizontal(
+    longitude: npt.NDArray[np.floating],
+    latitude: npt.NDArray[np.floating],
+    u_wind: npt.NDArray[np.floating],
+    v_wind: npt.NDArray[np.floating],
+    dt: npt.NDArray[np.timedelta64] | np.timedelta64,
+) -> tuple[npt.NDArray[np.floating], npt.NDArray[np.floating]]:
+    r"""Advect a particle in the horizontal plane.
+
+    This function calls :func:`advect_longitude` and :func:`advect_latitude` when
+    the position is far from the poles (<= 80.0 degrees). When the position is near
+    the poles (> 80.0 degrees), :func:`advect_longitude_and_latitude_near_poles`
+    is used instead.
+
+    Parameters
+    ----------
+    longitude : npt.NDArray[np.floating]
+        Original longitude, [:math:`\deg`]
+    latitude : npt.NDArray[np.floating]
+        Original latitude, [:math:`\deg`]
+    u_wind : npt.NDArray[np.floating]
+        Wind speed in the longitudinal direction, [:math:`m s^{-1}`]
+    v_wind : npt.NDArray[np.floating]
+        Wind speed in the latitudinal direction, [:math:`m s^{-1}`]
+    dt : npt.NDArray[np.timedelta64] | np.timedelta64
+        Advection timestep
+
+    Returns
+    -------
+    tuple[npt.NDArray[np.floating], npt.NDArray[np.floating]]
+        New longitude and latitude values, [:math:`\deg`]
+    """
+    near_poles = np.abs(latitude) > 80.0
+
+    longitude_out = np.empty_like(longitude)
+    latitude_out = np.empty_like(latitude)
+
+    # Use simple spherical advection if position is far from the poles (<= 80.0 degrees)
+    cond = ~near_poles
+    lon_cond = longitude[cond]
+    lat_cond = latitude[cond]
+    u_wind_cond = u_wind[cond]
+    v_wind_cond = v_wind[cond]
+    dt_cond = dt if isinstance(dt, np.timedelta64) else dt[cond]
+    longitude_out[cond] = advect_longitude(lon_cond, lat_cond, u_wind_cond, dt_cond)
+    latitude_out[cond] = advect_latitude(lat_cond, v_wind_cond, dt_cond)
+
+    # And use Cartesian-like advection if position is near the poles (> 80.0 degrees)
+    cond = near_poles
+    lon_cond = longitude[cond]
+    lat_cond = latitude[cond]
+    u_wind_cond = u_wind[cond]
+    v_wind_cond = v_wind[cond]
+    dt_cond = dt if isinstance(dt, np.timedelta64) else dt[cond]
+    lon_out_cond, lat_out_cond = advect_longitude_and_latitude_near_poles(
+        lon_cond, lat_cond, u_wind_cond, v_wind_cond, dt_cond
+    )
+    longitude_out[cond] = lon_out_cond
+    latitude_out[cond] = lat_out_cond
+
+    return longitude_out, latitude_out
+
+
 # ---------------
 # Grid properties
 # ---------------