pycontrails 0.54.5__cp310-cp310-win_amd64.whl → 0.54.7__cp310-cp310-win_amd64.whl

pycontrails/models/dry_advection.py

@@ -63,6 +63,15 @@ class DryAdvectionParams(models.AdvectionBuffers):
     # If None, only pointwise advection is simulated without wind shear effects.
     azimuth: float | None = 0.0
 
+    #: Add additional intermediate variables to the output vector.
+    #: This includes interpolated met variables and wind-shear-derived geometry.
+    verbose_outputs: bool = False
+
+    #: Whether to include ``source`` points in the output vector. Enabling allows
+    #: the user to view additional data (e.g., interpolated met variables) for
+    #: source points as well as evolved points.
+    include_source_in_output: bool = False
+
 
 class DryAdvection(models.Model):
     """Simulate "dry advection" of an emissions plume with an elliptical cross section.
@@ -154,42 +163,51 @@ class DryAdvection(models.Model):
         sedimentation_rate = self.params["sedimentation_rate"]
         dz_m = self.params["dz_m"]
         max_depth = self.params["max_depth"]
+        verbose_outputs = self.params["verbose_outputs"]
 
         source_time = self.source["time"]
         t0 = pd.Timestamp(source_time.min()).floor(pd.Timedelta(dt_integration)).to_numpy()
         t1 = source_time.max()
         timesteps = np.arange(t0 + dt_integration, t1 + dt_integration + max_age, dt_integration)
 
-        vector = GeoVectorDataset()
+        vector2 = GeoVectorDataset()
         met = None
 
         evolved = []
         for t in timesteps:
             filt = (source_time < t) & (source_time >= t - dt_integration)
-            vector = vector + self.source.filter(filt, copy=False)
+            vector1 = vector2 + self.source.filter(filt, copy=False)
 
-            t0 = vector["time"].min()
-            t1 = vector["time"].max()
+            t0 = vector1["time"].min()
+            t1 = vector1["time"].max()
             met = maybe_downselect_mds(self.met, met, t0, t1)
 
-            vector = _evolve_one_step(
+            vector2 = _evolve_one_step(
                 met,
-                vector,
+                vector1,
                 t,
                 sedimentation_rate=sedimentation_rate,
                 dz_m=dz_m,
                 max_depth=max_depth,
+                verbose_outputs=verbose_outputs,
                 **interp_kwargs,
             )
+            evolved.append(vector1)
 
-            filt = (vector["age"] <= max_age) & vector.coords_intersect_met(self.met)
-            vector = vector.filter(filt)
+            filt = (vector2["age"] <= max_age) & vector2.coords_intersect_met(self.met)
+            vector2 = vector2.filter(filt)
 
-            evolved.append(vector)
-            if not vector and np.all(source_time < t):
+            if not vector2 and np.all(source_time < t):
                 break
 
-        return GeoVectorDataset.sum(evolved, fill_value=np.nan)
+        evolved.append(vector2)
+        out = GeoVectorDataset.sum(evolved, fill_value=np.nan)
+
+        if self.params["include_source_in_output"]:
+            return out
+
+        filt = out["age"] > np.timedelta64(0, "ns")
+        return out.filter(filt)
 
     def _prepare_source(self) -> GeoVectorDataset:
         r"""Prepare :attr:`source` vector for advection by wind-shear-derived variables.
@@ -364,8 +382,12 @@ def _calc_geometry(
     dz_m: float,
     dt: npt.NDArray[np.timedelta64] | np.timedelta64,
     max_depth: float | None,
+    verbose_outputs: bool,
 ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
-    """Calculate wind-shear-derived geometry of evolved plume."""
+    """Calculate wind-shear-derived geometry of evolved plume.
+
+    This method mutates the input ``vector`` in place.
+    """
 
     u_wind = vector["u_wind"]
     v_wind = vector["v_wind"]
@@ -419,6 +441,11 @@ def _calc_geometry(
         eff_heat_rate=None,
     )
 
+    if verbose_outputs:
+        vector["ds_dz"] = ds_dz
+        vector["dsn_dz"] = dsn_dz
+        vector["dT_dz"] = dT_dz
+
     sigma_yy_2, sigma_zz_2, sigma_yz_2 = contrail_properties.plume_temporal_evolution(
         width,
         depth,
@@ -477,9 +504,13 @@ def _evolve_one_step(
     sedimentation_rate: float,
     dz_m: float,
     max_depth: float | None,
+    verbose_outputs: bool,
     **interp_kwargs: Any,
 ) -> GeoVectorDataset:
-    """Evolve plume geometry by one step."""
+    """Evolve plume geometry by one step.
+
+    This method mutates the input ``vector`` in place.
+    """
 
     _perform_interp_for_step(met, vector, dz_m, **interp_kwargs)
     u_wind = vector["u_wind"]
@@ -494,9 +525,9 @@ def _evolve_one_step(
     level_2 = geo.advect_level(
         vector.level,
         vertical_velocity,
-        0.0,
-        0.0,
-        dt,  # type: ignore[arg-type]
+        rho_air=0.0,
+        terminal_fall_speed=0.0,
+        dt=dt,  # type: ignore[arg-type]
     )
 
     out = GeoVectorDataset._from_fastpath(
@@ -518,9 +549,10 @@ def _evolve_one_step(
     # Attach wind-shear-derived geometry to output vector
     azimuth_2, width_2, depth_2, sigma_yz_2, area_eff_2 = _calc_geometry(
         vector,
-        dz_m,
-        dt,  # type: ignore[arg-type]
-        max_depth,  # type: ignore[arg-type]
+        dz_m=dz_m,
+        dt=dt,  # type: ignore[arg-type]
+        max_depth=max_depth,  # type: ignore[arg-type]
+        verbose_outputs=verbose_outputs,
     )
     out["azimuth"] = azimuth_2
     out["width"] = width_2

pycontrails/models/emissions/black_carbon.py

@@ -98,7 +98,7 @@ def flame_temperature(t_3: ArrayScalarLike) -> ArrayScalarLike:
     ArrayScalarLike
         Flame temperature at the combustion chamber, [:math:`K`]
     """
-    return 0.9 * t_3 + 2120
+    return 0.9 * t_3 + 2120.0
 
 
 def bc_mass_concentration_fox(
@@ -125,7 +125,11 @@ def bc_mass_concentration_fox(
     npt.NDArray[np.floating]:
         Black carbon mass concentration for ground conditions, [:math:`mg m^{-3}`]
     """
-    return fuel_flow * (356 * np.exp(-6390 / t_fl) - 608 * afr * np.exp(-19778 / t_fl))
+    # avoid float32 -> float64 promotion
+    coeff = 356.0 * np.exp(np.float32(-6390.0) / t_fl) - 608.0 * afr * np.exp(
+        np.float32(-19778.0) / t_fl
+    )
+    return fuel_flow * coeff
 
 
 def bc_mass_concentration_cruise_fox(
@@ -209,7 +213,7 @@ def dopelheuer_lecht_scaling_factor(
     ----------
     - :cite:`dopelheuerInfluenceEnginePerformance1998`
     """
-    exp_term = np.exp(20000 / t_fl_cru) / np.exp(20000 / t_fl_ref)
+    exp_term = np.exp(20000.0 / t_fl_cru - 20000.0 / t_fl_ref)
     return (afr_ref / afr_cru) ** 2.5 * (p_3_cru / p_3_ref) ** 1.35 * exp_term
 
 
@@ -295,7 +299,7 @@ def turbine_inlet_temperature_imfox(afr: npt.NDArray[np.floating]) -> npt.NDArra
     ----------
     - :cite:`abrahamsonPredictiveModelDevelopment2016`
     """
-    return 490 + 42266 / afr
+    return 490.0 + 42266.0 / afr
 
 
 def bc_mass_concentration_imfox(
@@ -325,9 +329,10 @@ def bc_mass_concentration_imfox(
     npt.NDArray[np.floating]
         Black carbon mass concentration, [:math:`mg m^{-3}`]
     """
-    exp_term = np.exp(13.6 - fuel_hydrogen)
-    formation_term = 295 * np.exp(-6390 / t_4)
-    oxidation_term = 608 * afr * np.exp(-19778 / t_4)
+    # avoid float32 -> float64 promotion
+    exp_term = np.exp(np.float32(13.6) - fuel_hydrogen)
+    formation_term = 295.0 * np.exp(np.float32(-6390.0) / t_4)
+    oxidation_term = 608.0 * afr * np.exp(np.float32(-19778.0) / t_4)
     return fuel_flow_per_engine * exp_term * (formation_term - oxidation_term)
 
 
@@ -453,11 +458,11 @@ def number_emissions_index_fractal_aggregates(
     nvpm_ei_m: npt.NDArray[np.floating],
     gmd: npt.NDArray[np.floating],
     *,
-    gsd: float | npt.NDArray[np.floating] = 1.80,
-    rho_bc: float = 1770,
-    k_tem: float = 1.621e-5,
-    d_tem: float = 0.39,
-    d_fm: float = 2.76,
+    gsd: float | np.floating | npt.NDArray[np.floating] = np.float32(1.80),  # avoid promotion
+    rho_bc: float | np.floating = np.float32(1770.0),
+    k_tem: float | np.floating = np.float32(1.621e-5),
+    d_tem: float | np.floating = np.float32(0.39),
+    d_fm: float | np.floating = np.float32(2.76),
 ) -> npt.NDArray[np.floating]:
     """
     Estimate the black carbon number emission index using the fractal aggregates (FA) model.
@@ -494,9 +499,9 @@ def number_emissions_index_fractal_aggregates(
     - ``rho_bc``: :cite:`parkMeasurementInherentMaterial2004`
     - ``k_tem``, ``d_tem``: :cite:`dastanpourObservationsCorrelationPrimary2014`
     """
-    phi = 3 * d_tem + (1 - d_tem) * d_fm
+    phi = 3.0 * d_tem + (1.0 - d_tem) * d_fm
     exponential_term = np.exp(0.5 * phi**2 * np.log(gsd) ** 2)
-    denom = rho_bc * (np.pi / 6) * k_tem ** (3 - d_fm) * gmd**phi * exponential_term
+    denom = rho_bc * (np.pi / 6.0) * k_tem ** (3.0 - d_fm) * gmd**phi * exponential_term
     return nvpm_ei_m / denom
 
 

pycontrails/models/emissions/emissions.py

@@ -169,7 +169,7 @@ class Emissions(Model):
             )
 
         if "n_engine" not in self.source.attrs:
-            aircraft_type = self.source.attrs.get("aircraft_type")
+            aircraft_type = self.source.get_constant("aircraft_type", None)
             self.source.attrs["n_engine"] = self.default_engines.at[aircraft_type, "n_engine"]
 
         try:
@@ -192,7 +192,7 @@ class Emissions(Model):
             try:
                 edb_gaseous = self.edb_engine_gaseous[engine_uid]  # type: ignore[index]
             except KeyError:
-                self.source["thrust_setting"] = np.full(shape=len(self.source), fill_value=np.nan)
+                self.source["thrust_setting"] = np.full(len(self.source), np.nan, dtype=np.float32)
             else:
                 self.source["thrust_setting"] = get_thrust_setting(
                     edb_gaseous,
@@ -297,9 +297,9 @@ class Emissions(Model):
         """
         self.source.attrs["gaseous_data_source"] = "Constant"
 
-        nox_ei = np.full(shape=len(self.source), fill_value=15.14)
-        co_ei = np.full(shape=len(self.source), fill_value=3.61)
-        hc_ei = np.full(shape=len(self.source), fill_value=0.520)
+        nox_ei = np.full(shape=len(self.source), fill_value=15.14, dtype=np.float32)
+        co_ei = np.full(shape=len(self.source), fill_value=3.61, dtype=np.float32)
+        hc_ei = np.full(shape=len(self.source), fill_value=0.520, dtype=np.float32)
 
         self.source["nox_ei"] = nox_ei * 1e-3  # g-NOx/kg-fuel to kg-NOx/kg-fuel
         self.source["co_ei"] = co_ei * 1e-3  # g-CO/kg-fuel to kg-CO/kg-fuel
@@ -493,8 +493,8 @@ class Emissions(Model):
         - :cite:`schumannDehydrationEffectsContrails2015`
         """
         nvpm_data_source = "Constant"
-        nvpm_ei_m = np.full(shape=len(self.source), fill_value=(0.088 * 1e-3))  # g to kg
-        nvpm_ei_n = np.full(shape=len(self.source), fill_value=self.params["default_nvpm_ei_n"])
+        nvpm_ei_m = np.full(len(self.source), 0.088 * 1e-3, dtype=np.float32)  # g to kg
+        nvpm_ei_n = np.full(len(self.source), self.params["default_nvpm_ei_n"], dtype=np.float32)
         return nvpm_data_source, nvpm_ei_m, nvpm_ei_n
 
     def _total_pollutant_emissions(self) -> None:
@@ -916,7 +916,7 @@ def get_thrust_setting(
     )
 
     thrust_setting = fuel_flow_per_engine / edb_gaseous.ff_100
-    thrust_setting.clip(0.03, 1, out=thrust_setting)  # clip in place
+    thrust_setting.clip(0.03, 1.0, out=thrust_setting)  # clip in place
     return thrust_setting
 
 

pycontrails/models/humidity_scaling/humidity_scaling.py

@@ -654,7 +654,7 @@ def histogram_matching(
         as a numpy array with the same shape and dtype as ``era5_rhi``.
     """
     if level_type not in ["pressure", "model"]:
-        msg = f"Invalid 'level_type' value '{level_type}'. " "Must be one of ['pressure', 'model']."
+        msg = f"Invalid 'level_type' value '{level_type}'. Must be one of ['pressure', 'model']."
         raise ValueError(msg)
     df = _load_quantiles(level_type)
     iagos_quantiles = df[("iagos", "iagos")]

pycontrails/models/pcc.py

@@ -186,8 +186,7 @@ class PCC(Model):
 
             # issue recombining groups arises if "level" is in dims
             # convert "level" dimension to coordinate
-            b_crit_potential = b_crit_potential.squeeze("level")
-            return b_crit_potential
+            return b_crit_potential.squeeze("level")
 
         # apply calculation per pressure level
         return (

pycontrails/models/ps_model/ps_model.py

@@ -7,7 +7,7 @@ import functools
 import pathlib
 import sys
 from collections.abc import Mapping
-from typing import Any, NoReturn, overload
+from typing import Any
 
 if sys.version_info >= (3, 12):
     from typing import override
@@ -25,7 +25,6 @@ from pycontrails.core.aircraft_performance import (
     AircraftPerformanceData,
     AircraftPerformanceParams,
 )
-from pycontrails.core.fleet import Fleet
 from pycontrails.core.flight import Flight
 from pycontrails.core.met import MetDataset
 from pycontrails.core.met_var import AirTemperature, EastwardWind, MetVariable, NorthwardWind
@@ -118,38 +117,11 @@ class PSFlight(AircraftPerformance):
             raise KeyError(msg)
         return False
 
-    @overload
-    def eval(self, source: Fleet, **params: Any) -> Fleet: ...
-
-    @overload
-    def eval(self, source: Flight, **params: Any) -> Flight: ...
-
-    @overload
-    def eval(self, source: None = ..., **params: Any) -> NoReturn: ...
-
     @override
-    def eval(self, source: Flight | None = None, **params: Any) -> Flight:
-        self.update_params(params)
-        self.set_source(source)
-        self.source = self.require_source_type(Flight)
-        self.downselect_met()
-        self.set_source_met()
-
-        # 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
-
-    def _eval_flight(self, fl: Flight) -> Flight:
+    def eval_flight(self, fl: Flight) -> Flight:
         # Ensure aircraft type is available
         try:
-            aircraft_type = fl.attrs["aircraft_type"]
+            aircraft_type = fl.get_constant("aircraft_type")
         except KeyError as exc:
             msg = "`aircraft_type` required on flight attrs"
             raise KeyError(msg) from exc

pycontrails/models/ps_model/ps_operational_limits.py

@@ -390,7 +390,7 @@ def minimum_mach_num(
         )
         return amass_max - aircraft_mass
 
-    m = scipy.optimize.newton(
+    return scipy.optimize.newton(
         excess_mass,
         args=(
             air_pressure,
@@ -404,8 +404,6 @@ def minimum_mach_num(
         tol=1e-4,
     )
 
-    return m
-
 
 def maximum_mach_num(
     altitude_ft: ArrayOrFloat,
@@ -450,7 +448,7 @@ def maximum_mach_num(
         atyp_param.p_inf_co,
     )
 
-    max_mach = scipy.optimize.newton(
+    return scipy.optimize.newton(
         func=get_excess_thrust_available,
         args=(air_temperature, air_pressure, aircraft_mass, theta, atyp_param),
         x0=mach_num_op_lim,
@@ -458,8 +456,6 @@ def maximum_mach_num(
         tol=1e-4,
     ).clip(max=mach_num_op_lim)
 
-    return max_mach
-
 
 # ----------------
 # Fuel flow limits

pycontrails/models/tau_cirrus.py

@@ -45,7 +45,8 @@ def tau_cirrus(met: MetDataset) -> xr.DataArray:
     met : MetDataset
         A MetDataset with the following variables:
         - "air_temperature"
-        - "specific_cloud_ice_water_content" or "ice_water_mixing_ratio"
+        - "mass_fraction_of_cloud_ice_in_air", "specific_cloud_ice_water_content",
+          or "ice_water_mixing_ratio"
 
     Returns
     -------
@@ -64,15 +65,21 @@ def tau_cirrus(met: MetDataset) -> xr.DataArray:
     geopotential_height = _geopotential_height(met)
 
     # TODO: these are not *quite* the same, though we treat them the same for now
-    # ECMWF "specific_cloud_ice_water_content" is mass ice per mass of *moist* air
-    # GFS "ice_water_mixing_ratio" is mass ice per mass of *dry* air
+    # The generic "mass_fraction_of_cloud_ice_in_air" and ECMWF "specific_cloud_ice_water_content"
+    # are mass ice per mass of *moist* air,
+    # whereas GFS "ice_water_mixing_ratio" is mass ice per mass of *dry* air
     #
     # The method `cirrus_effective_extinction_coef` uses input of mass ice per mass of *dry* air,
-    # so the ECMWF data is not quite right.
-    try:
+    # so only the GFS data is exactly right.
+    if "mass_fraction_of_cloud_ice_in_air" in met.data:
+        ciwc = met.data["mass_fraction_of_cloud_ice_in_air"]
+    elif "specific_cloud_ice_water_content" in met.data:
         ciwc = met.data["specific_cloud_ice_water_content"]
-    except KeyError:
+    elif "ice_water_mixing_ratio" in met.data:
         ciwc = met.data["ice_water_mixing_ratio"]
+    else:
+        msg = "Could not find cloud ice variable"
+        raise KeyError(msg)
 
     beta_e = cirrus_effective_extinction_coef(
         ciwc,

pycontrails/physics/constants.py

@@ -112,5 +112,6 @@ c_r: float = 0.9
 # Flight
 # ------
 
-#: Nominal rate of climb/descent of aircraft [:math:`m \ s^{-1}``]
+#: Nominal rate of climb/descent of aircraft [:math:`m \ s^{-1}`].
+#: Note [:math:`12.7 m \ s^{-1} = 2500 ft \ min^{-1}`].
 nominal_rocd: float = 12.7

pycontrails/physics/geo.py

@@ -516,7 +516,7 @@ def solar_constant(theta_rad: ArrayLike) -> ArrayLike:
         + (0.000077 * np.sin(theta_rad * 2))
     )
 
-    return constants.solar_constant * orbital_effect
+    return constants.solar_constant * orbital_effect  # type: ignore[return-value]
 
 
 def cosine_solar_zenith_angle(
@@ -662,7 +662,7 @@ def solar_declination_angle(theta_rad: ArrayLike) -> ArrayLike:
     :func:`cosine_solar_zenith_angle`
     """
     return (
-        0.396372
+        0.396372  # type: ignore[return-value]
         - (22.91327 * np.cos(theta_rad))
         + (4.02543 * np.sin(theta_rad))
         - (0.387205 * np.cos(2 * theta_rad))
@@ -729,7 +729,7 @@ def orbital_correction_for_solar_hour_angle(theta_rad: ArrayLike) -> ArrayLike:
     Tested against :cite:`noaaSolarCalculationDetails`
     """
     return (
-        0.004297
+        0.004297  # type: ignore[return-value]
         + (0.107029 * np.cos(theta_rad))
         - (1.837877 * np.sin(theta_rad))
         - (0.837378 * np.cos(2 * theta_rad))

{pycontrails-0.54.5.dist-info → pycontrails-0.54.7.dist-info}/METADATA

@@ -1,8 +1,8 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: pycontrails
-Version: 0.54.5
+Version: 0.54.7
 Summary: Python library for modeling aviation climate impacts
-Author-email: Breakthrough Energy <py@contrails.org>
+Author-email: "Contrails.org" <py@contrails.org>
 License: Apache-2.0
 Project-URL: Changelog, https://py.contrails.org/changelog.html
 Project-URL: Documentation, https://py.contrails.org
@@ -29,7 +29,7 @@ License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: dask>=2022.3
 Requires-Dist: numpy>=1.22
-Requires-Dist: pandas>=2.2
+Requires-Dist: pandas>=2.0
 Requires-Dist: scipy>=1.10
 Requires-Dist: typing-extensions>=4.5; python_version < "3.12"
 Requires-Dist: xarray>=2022.3
@@ -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.dist-info → pycontrails-0.54.7.dist-info}/NOTICE

@@ -1,4 +1,4 @@
-Copyright (c) 2021-present Breakthrough Energy
+Copyright (c) 2021-present Contrails.org and the Breakthrough Energy Foundation
 
 
 Attribution