pycontrails 0.54.12__cp311-cp311-macosx_11_0_arm64.whl → 0.55.0__cp311-cp311-macosx_11_0_arm64.whl

pycontrails/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.54.12'
-__version_tuple__ = version_tuple = (0, 54, 12)
+__version__ = version = '0.55.0'
+__version_tuple__ = version_tuple = (0, 55, 0)
 
-__commit_id__ = commit_id = 'g5920a0c98'
+__commit_id__ = commit_id = 'g113bce45e'

pycontrails/models/cocip/cocip.py

@@ -27,7 +27,7 @@ from pycontrails.core.met_var import MetVariable
 from pycontrails.core.models import Model, interpolate_met
 from pycontrails.core.vector import GeoVectorDataset, VectorDataDict
 from pycontrails.datalib import ecmwf, gfs
-from pycontrails.models import sac, tau_cirrus
+from pycontrails.models import extended_k15, sac, tau_cirrus
 from pycontrails.models.cocip import (
     contrail_properties,
     radiative_forcing,
@@ -58,7 +58,7 @@ class Cocip(Model):
     rad : MetDataset
         Single level dataset containing top of atmosphere radiation fluxes.
         See *Notes* for variable names by data source.
-    params : dict[str, Any], optional
+    params : dict[str, Any] | None, optional
         Override Cocip model parameters with dictionary.
         See :class:`CocipFlightParams` for model parameters.
     **params_kwargs : Any
@@ -411,7 +411,7 @@ class Cocip(Model):
 
         Returns
         -------
-        Flight | list[Flight] | NoReturn
+        Flight | list[Flight]
             Flight(s) with updated Contrail data. The model parameter "verbose_outputs"
             determines the variables on the return flight object.
 
@@ -489,7 +489,7 @@ class Cocip(Model):
 
         Returns
         -------
-        tuple[MetVariable]
+        tuple[MetVariable, ...]
             List of model-agnostic variants of required variables
         """
         available = set(met_var.MET_VARIABLES)
@@ -501,7 +501,7 @@ class Cocip(Model):
 
         Returns
         -------
-        tuple[MetVariable]
+        tuple[MetVariable, ...]
             List of ECMWF-specific variants of required variables
         """
         available = set(ecmwf.ECMWF_VARIABLES)
@@ -513,7 +513,7 @@ class Cocip(Model):
 
         Returns
         -------
-        tuple[MetVariable]
+        tuple[MetVariable, ...]
             List of GFS-specific variants of required variables
         """
         available = set(gfs.GFS_VARIABLES)
@@ -981,6 +981,30 @@ class Cocip(Model):
         )
         iwc_1 = contrail_properties.iwc_post_wake_vortex(iwc, iwc_ad)
 
+        if self.params["vpm_activation"]:
+            # We can add a Cocip parameter for T_exhaust, vpm_ei_n, and particles
+            aei = extended_k15.droplet_apparent_emission_index(
+                specific_humidity=specific_humidity,
+                T_ambient=air_temperature,
+                T_exhaust=self.source.attrs.get("T_exhaust", extended_k15.DEFAULT_EXHAUST_T),
+                air_pressure=air_pressure,
+                nvpm_ei_n=nvpm_ei_n,
+                vpm_ei_n=self.source.attrs.get("vpm_ei_n", extended_k15.DEFAULT_VPM_EI_N),
+                G=self._sac_flight["G"],
+            )
+            min_aei = None  # don't clip
+
+        else:
+            f_activation = contrail_properties.ice_particle_activation_rate(
+                air_temperature, T_critical_sac
+            )
+            aei = nvpm_ei_n * f_activation
+            min_aei = self.params["min_ice_particle_number_nvpm_ei_n"]
+
+        n_ice_per_m_0 = contrail_properties.initial_ice_particle_number(
+            aei=aei, fuel_dist=fuel_dist, min_aei=min_aei
+        )
+
         if self.params["unterstrasser_ice_survival_fraction"]:
             wingspan = self._sac_flight.get_data_or_attr("wingspan")
             rhi_0 = thermo.rhi(specific_humidity, air_temperature, air_pressure)
@@ -997,13 +1021,6 @@ class Cocip(Model):
         else:
             f_surv = contrail_properties.ice_particle_survival_fraction(iwc, iwc_1)
 
-        n_ice_per_m_0 = contrail_properties.initial_ice_particle_number(
-            nvpm_ei_n=nvpm_ei_n,
-            fuel_dist=fuel_dist,
-            air_temperature=air_temperature,
-            T_crit_sac=T_critical_sac,
-            min_ice_particle_number_nvpm_ei_n=self.params["min_ice_particle_number_nvpm_ei_n"],
-        )
         n_ice_per_m_1 = n_ice_per_m_0 * f_surv
 
         # Check for persistent initial_contrails

pycontrails/models/cocip/cocip_params.py

@@ -195,8 +195,8 @@ class CocipParams(AdvectionBuffers):
     nvpm_ei_n_enhancement_factor: float = 1.0
 
     #: Lower bound for ``nvpm_ei_n`` to account for ambient aerosol
-    #: particles for newer engines, [:math:`kg^{-1}`]
-    min_ice_particle_number_nvpm_ei_n: float = 1e13
+    #: particles for newer engines, [:math:`kg^{-1}`]. Set to None to disable.
+    min_ice_particle_number_nvpm_ei_n: float | None = 1e13
 
     #: Upper bound for contrail plume depth, constraining it to realistic values.
     #: CoCiP only uses the ambient conditions at the mid-point of the Gaussian plume,
@@ -223,11 +223,17 @@ class CocipParams(AdvectionBuffers):
     #:  .. versionadded:: 0.28.9
     radiative_heating_effects: bool = False
 
+    #: Experimental. Apply the extended K15 model to account for vPM activation.
+    #: See the preprint `<https://doi.org/10.5194/egusphere-2025-1717>`_ for details.
+    #:
+    #: .. versionadded:: 0.55.0
+    vpm_activation: bool = False
+
     #: Experimental. Radiative effects due to contrail-contrail overlapping
     #: Account for change in local contrail shortwave and longwave radiative forcing
     #: due to contrail-contrail overlapping.
     #:
-    #: .. versionadded:: 0.45
+    #: .. versionadded:: 0.45.0
     contrail_contrail_overlapping: bool = False
 
     #: Experimental. Contrail-contrail overlapping altitude interval

pycontrails/models/cocip/cocip_uncertainty.py

@@ -40,9 +40,9 @@ class habit_dirichlet(rv_frozen):
 
         Parameters
         ----------
-        *args
+        *args : Any
             Used to create a number of habit distributions
-        **kwds
+        **kwds : Any
             Passed through to :func:`scipy.stats.dirichlet.rvs()`
 
         Returns
@@ -190,7 +190,7 @@ class CocipUncertaintyParams(CocipParams):
 
         Returns
         -------
-        dict[str, dict[str, Any]]
+        dict[str, rv_frozen]
             Uncertainty parameters and values
         """
         # handle these differently starting in version 0.27.0
@@ -230,7 +230,7 @@ class CocipUncertaintyParams(CocipParams):
 
         Returns
         -------
-        dict[str, float | npt.NDArray[np.floating]]
+        dict[str, np.float64 | npt.NDArray[np.floating]]
             Dictionary of random parameters. Dictionary keys consists of names of parameters in
             `CocipParams` to be overridden by random value.
 

pycontrails/models/cocip/contrail_properties.py

@@ -202,32 +202,32 @@ def iwc_post_wake_vortex(
 
 
 def initial_ice_particle_number(
-    nvpm_ei_n: npt.NDArray[np.floating],
+    aei: npt.NDArray[np.floating],
     fuel_dist: npt.NDArray[np.floating],
-    air_temperature: npt.NDArray[np.floating],
-    T_crit_sac: npt.NDArray[np.floating],
-    min_ice_particle_number_nvpm_ei_n: float,
+    min_aei: float | None,
 ) -> npt.NDArray[np.floating]:
     """Calculate the initial number of ice particles per distance after the wake vortex phase.
 
-    The initial number of ice particle per distance is calculated from the black
-    carbon number emissions index ``nvpm_ei_n`` and fuel burn per distance ``fuel_dist``.
-    Note that a lower bound for ``nvpm_ei_n`` is set at ``1e13`` :math:`kg^{-1}` to account
+    The initial number of ice particle per distance is calculated from the activated apparent
+    emissions index ``aei`` and fuel burn per distance ``fuel_dist``.
+    Note that a lower bound for ``aei`` is set at ``1e13`` :math:`kg^{-1}` to account
     for the activation of ambient aerosol particles and organic volatile particles.
 
+    .. versionchanged:: 0.55
+
+        The signature of this function has changed. The parameter ``aei`` is now
+        expected to be the previous ``npvm_ei_n`` multiplied by the activation
+        fraction ``f_activation``.
+
     Parameters
     ----------
-    nvpm_ei_n : npt.NDArray[np.floating]
-        black carbon number emissions index, [:math:`kg^{-1}`]
+    aei : npt.NDArray[np.floating]
+        Apparent contrail emissions index, [:math:`kg^{-1}`]
     fuel_dist : npt.NDArray[np.floating]
-        fuel consumption of the flight segment per distance traveled, [:math:`kg m^{-1}`]
-    air_temperature : npt.NDArray[np.floating]
-        ambient temperature for each waypoint, [:math:`K`]
-    T_crit_sac : npt.NDArray[np.floating]
-        estimated Schmidt-Appleman temperature threshold for contrail formation, [:math:`K`]
-    min_ice_particle_number_nvpm_ei_n : float
-        lower bound for nvpm_ei_n to account for ambient aerosol particles for
-        newer engines [:math:`kg^{-1}`]
+        Fuel consumption of the flight segment per distance traveled, [:math:`kg m^{-1}`]
+    min_aei : float | None
+        Lower bound for ``aei`` to account for ambient aerosol particles for
+        newer engines [:math:`kg^{-1}`]. If None, no clipping is applied.
 
     Returns
     -------
@@ -235,9 +235,9 @@ def initial_ice_particle_number(
         The initial number of ice particles per distance before the wake vortex
         phase, [:math:`# m^{-1}`]
     """
-    f_activation = ice_particle_activation_rate(air_temperature, T_crit_sac)
-    nvpm_ei_n_activated = nvpm_ei_n * f_activation
-    return fuel_dist * np.maximum(nvpm_ei_n_activated, min_ice_particle_number_nvpm_ei_n)
+    if min_aei is not None:
+        aei = np.clip(aei, min=min_aei)  # type: ignore[arg-type,call-overload]
+    return fuel_dist * aei
 
 
 def ice_particle_activation_rate(
@@ -462,9 +462,9 @@ def _within_range(
     ----------
     val : np.ndarray
         value of selected contrail property
-    max : np.ndarray | float | np.timedelta64 | None, optional
+    max : float | np.timedelta64 | None, optional
         Upper bound. If None, no upper bound is imposed. None by default.
-    min : np.ndarray | float | np.timedelta64 | None, optional
+    min : float | np.timedelta64 | None, optional
         Lower bound. If None, no lower bound is imposed. None by default.
 
     Returns
@@ -585,9 +585,9 @@ def contrail_vertices(
 
     Returns
     -------
-    tuple[npt.NDArray[np.floating], npt.NDArray[np.floating], npt.NDArray[np.floating], npt.NDArray[np.floating]]
+    tuple
         (lon_1, lat_1, lon_2, lat_2, lon_3, lat_3, lon_4, lat_4) degrees
-    """  # noqa: E501
+    """
     dlon_width = units.m_to_longitude_distance(width * sin_a * 0.5, lat)
     dlat_width = units.m_to_latitude_distance(width * cos_a * 0.5)
 
@@ -888,9 +888,9 @@ def vertical_diffusivity(
         Temperature gradient with respect to altitude (dz), [:math:`K m^{-1}`]
     depth_eff : npt.NDArray[np.floating]
         Effective depth of the contrail plume, [:math:`m`]
-    terminal_fall_speed : npt.NDArray[np.floating]
+    terminal_fall_speed : npt.NDArray[np.floating] | float
         Terminal fall speed of contrail ice particles, [:math:`m s^{-1}`]
-    sedimentation_impact_factor : float
+    sedimentation_impact_factor : npt.NDArray[np.floating] | float
         Enhancement parameter denoted by `f_T` in eq. (35) Schumann (2012).
     eff_heat_rate: npt.NDArray[np.floating] | None
         Effective heating rate, i.e., rate of which the contrail plume
@@ -1506,7 +1506,7 @@ def mean_energy_flux_per_m(
     rad_flux_per_m : npt.NDArray[np.floating]
         Mean radiative flux between time steps for waypoint, [:math:`W m^{-1}`].
         See :func:`mean_radiative_flux_per_m`.
-    dt : npt.NDArray[np.timedelta64]
+    dt : npt.NDArray[np.timedelta64] | np.timedelta64
         timedelta of integration timestep for each waypoint.
 
     Returns

pycontrails/models/cocip/radiative_forcing.py

@@ -241,7 +241,7 @@ def habit_weight_regime_idx(
 
 def effective_radius_by_habit(
     r_vol_um: npt.NDArray[np.floating], habit_idx: npt.NDArray[np.intp]
-) -> np.ndarray:
+) -> npt.NDArray[np.floating]:
     r"""Calculate the effective radius ``r_eff_um`` via the mean ice particle radius and habit type.
 
     The ``habit_idx`` corresponds to the habit types in ``rf_const.habits``.
@@ -479,7 +479,7 @@ def longwave_radiative_forcing(
     habit_weights_ : npt.NDArray[np.floating]
         Weights to different ice particle habits for each waypoint,
         ``n_waypoints x 8`` (habit) columns, [:math:`[0 - 1]`]
-    r_eff_um : npt.NDArray[np.floating], optional
+    r_eff_um : npt.NDArray[np.floating] | None, optional
         Provide effective radius corresponding to elements in ``r_vol_um``, [:math:`\mu m`].
         Defaults to None, which means the effective radius will be calculated using ``r_vol_um``
         and habit types in :func:`effective_radius_by_habit`.
@@ -583,7 +583,7 @@ def shortwave_radiative_forcing(
     habit_weights_ : npt.NDArray[np.floating]
         Weights to different ice particle habits for each waypoint,
         ``n_waypoints x 8`` (habit) columns, [:math:`[0 - 1]`]
-    r_eff_um : npt.NDArray[np.floating], optional
+    r_eff_um : npt.NDArray[np.floating] | None, optional
         Provide effective radius corresponding to elements in ``r_vol_um``, [:math:`\mu m`].
         Defaults to None, which means the effective radius will be calculated using ``r_vol_um``
         and habit types in :func:`effective_radius_by_habit`.
@@ -923,7 +923,7 @@ def contrail_contrail_overlap_radiative_effects(
     min_altitude_m : float
         Minimum altitude domain in simulation, [:math:`m`]
         See :attr:`CocipParams.min_altitude_m`
-    max_altitude_m
+    max_altitude_m : float
         Maximum altitude domain in simulation, [:math:`m`]
         See :attr:`CocipParams.min_altitude_m`
     dz_overlap_m : float

pycontrails/models/cocip/unterstrasser_wake_vortex.py

@@ -284,7 +284,7 @@ def z_emit_length_scale_analytical(
 
     Parameters
     ----------
-    rho_emit : npt.NDArray[np.floating] | float
+    rho_emit : npt.NDArray[np.floating]
         Aircraft-emitted water vapour concentration in the plume, [:math:`kg m^{-3}`]
     air_temperature : npt.NDArray[np.floating]
         ambient temperature for each waypoint, [:math:`K`]
@@ -317,7 +317,7 @@ def z_emit_length_scale_numerical(
 
     Parameters
     ----------
-    rho_emit : npt.NDArray[np.floating] | float
+    rho_emit : npt.NDArray[np.floating]
         Aircraft-emitted water vapour concentration in the plume, [:math:`kg m^{-3}`]
     air_temperature : npt.NDArray[np.floating]
         ambient temperature for each waypoint, [:math:`K`]
@@ -365,7 +365,7 @@ def plume_area(wingspan: npt.NDArray[np.floating] | float) -> npt.NDArray[np.flo
 
     Returns
     -------
-    float
+    npt.NDArray[np.floating] | float
         Area of two wake-vortex plumes, [:math:`m^{2}`]
 
     Notes
@@ -396,7 +396,7 @@ def z_desc_length_scale(
         pressure altitude at each waypoint, [:math:`Pa`]
     true_airspeed : npt.NDArray[np.floating]
         true airspeed for each waypoint, [:math:`m s^{-1}`]
-    aircraft_mass : npt.NDArray[np.floating] | float
+    aircraft_mass : npt.NDArray[np.floating]
         aircraft mass for each waypoint, [:math:`kg`]
     dT_dz : npt.NDArray[np.floating]
         potential temperature gradient, [:math:`K m^{-1}`]
@@ -436,7 +436,7 @@ def _initial_wake_vortex_circulation(
         pressure altitude at each waypoint, [:math:`Pa`]
     true_airspeed : npt.NDArray[np.floating]
         true airspeed for each waypoint, [:math:`m s^{-1}`]
-    aircraft_mass : npt.NDArray[np.floating] | float
+    aircraft_mass : npt.NDArray[np.floating]
         aircraft mass for each waypoint, [:math:`kg`]
 
     Returns

pycontrails/models/cocip/wake_vortex.py

@@ -39,7 +39,7 @@ def max_downward_displacement(
     ds_dz: npt.NDArray[np.floating],
     air_pressure: npt.NDArray[np.floating],
     effective_vertical_resolution: float,
-    wind_shear_enhancement_exponent: float | npt.NDArray[np.floating],
+    wind_shear_enhancement_exponent: npt.NDArray[np.floating] | float,
 ) -> npt.NDArray[np.floating]:
     """
     Calculate the maximum contrail downward displacement after the wake vortex phase.
@@ -117,11 +117,11 @@ def effective_time_scale(
 
     Parameters
     ----------
-    wingspan : npt.NDArray[np.floating]
+    wingspan : npt.NDArray[np.floating] | float
         aircraft wingspan, [:math:`m`]
     true_airspeed : npt.NDArray[np.floating]
         true airspeed for each waypoint, [:math:`m \ s^{-1}`]
-    aircraft_mass : npt.NDArray[np.floating]
+    aircraft_mass : npt.NDArray[np.floating] | float
         aircraft mass for each waypoint, [:math:`kg`]
     rho_air : npt.NDArray[np.floating]
         density of air for each waypoint, [:math:`kg \ m^{-3}`]
@@ -260,7 +260,7 @@ def wake_vortex_separation(
 
     Returns
     -------
-    npt.NDArray[np.floating]
+    npt.NDArray[np.floating] | float
         wake vortex separation, [:math:`m`]
     """
     return (np.pi * wingspan) / 4.0
@@ -320,9 +320,9 @@ def normalized_dissipation_rate(
         aircraft wingspan, [:math:`m`]
     true_airspeed : npt.NDArray[np.floating]
         true airspeed for each waypoint, [:math:`m s^{-1}`]
-    aircraft_mass : npt.NDArray[np.floating]
+    aircraft_mass : npt.NDArray[np.floating] | float
         aircraft mass for each waypoint, [:math:`kg`]
-    rho_air : npt.NDArray[np.floating]
+    rho_air : npt.NDArray[np.floating] | float
         density of air for each waypoint, [:math:`kg m^{-3}`]
 
     Returns

pycontrails/models/cocipgrid/cocip_grid.py

@@ -16,7 +16,7 @@ import pycontrails
 from pycontrails.core import models
 from pycontrails.core.met import MetDataset, maybe_downselect_mds
 from pycontrails.core.vector import GeoVectorDataset, VectorDataset
-from pycontrails.models import humidity_scaling, sac
+from pycontrails.models import extended_k15, humidity_scaling, sac
 from pycontrails.models.cocip import cocip, contrail_properties, wake_vortex, wind_shear
 from pycontrails.models.cocipgrid.cocip_grid_params import CocipGridParams
 from pycontrails.models.emissions import Emissions
@@ -36,13 +36,15 @@ class CocipGrid(models.Model):
 
     Parameters
     ----------
-    met, rad : MetDataset
+    met : MetDataset
         CoCiP-specific met data to interpolate against
-    params : dict[str, Any], optional
+    rad : MetDataset
+        CoCiP-specific radiation data to interpolate against
+    params : dict[str, Any] | None, optional
         Override :class:`CocipGridParams` defaults. Most notably, the model is highly
         dependent on the parameter ``dt_integration``. Memory usage is also affected by
         parameters ``met_slice_dt`` and ``target_split_size``.
-    param_kwargs : Any
+    **params_kwargs : Any
         Override CocipGridParams defaults with arbitrary keyword arguments.
 
     Notes
@@ -126,10 +128,7 @@ class CocipGrid(models.Model):
             raise NotImplementedError(msg)
 
         if self.params["unterstrasser_ice_survival_fraction"]:
-            msg = (
-                "Parameter 'unterstrasser_ice_survival_fraction' is not "
-                "yet implemented in CocipGrid"
-            )
+            msg = "Parameter 'unterstrasser_ice_survival_fraction' is not implemented in CocipGrid"
             raise NotImplementedError(msg)
 
         self._target_dtype = np.result_type(*self.met.data.values())
@@ -767,20 +766,26 @@ class CocipGrid(models.Model):
 
         Parameters
         ----------
-        level : level: npt.NDArray[np.floating] | list[float] | float
+        level : npt.NDArray[np.floating] | list[float] | float
             Pressure levels for gridded cocip.
             To avoid interpolating outside of the passed ``met`` and ``rad`` data, this
             parameter should avoid the extreme values of the ``met`` and `rad` levels.
             If ``met`` is already defined, a good choice for ``level`` is
             ``met.data['level'].values[1: -1]``.
-        time: npt.NDArray[np.datetime64 | list[np.datetime64] | np.datetime64,
+        time : npt.NDArray[np.datetime64] | list[np.datetime64] | np.datetime64
             One or more time values for gridded cocip.
-        longitude, latitude : npt.NDArray[np.floating] | list[float], optional
-            Longitude and latitude arrays, by default None. If not specified, values of
+        longitude : npt.NDArray[np.floating] | list[float] | None, optional
+            Longitude array, by default None. If not specified, values of
+            ``lon_step`` and ``lat_step`` are used to define ``longitude`` and ``latitude``.
+        latitude : npt.NDArray[np.floating] | list[float] | None, optional
+            Latitude array, by default None. If not specified, values of
             ``lon_step`` and ``lat_step`` are used to define ``longitude`` and ``latitude``.
-        lon_step, lat_step : float, optional
-            Longitude and latitude resolution, by default 1.0.
-            Only used if parameter ``longitude`` (respective ``latitude``) not specified.
+        lon_step : float, optional
+            Longitude resolution, by default 1.0.
+            Only used if parameter ``longitude`` not specified.
+        lat_step : float, optional
+            Latitude resolution, by default 1.0.
+            Only used if parameter ``latitude`` not specified.
 
         Returns
         -------
@@ -899,14 +904,16 @@ def run_interpolators(
     ----------
     vector : GeoVectorDataset
         Grid points.
-    met, rad : MetDataset
-        CoCiP met and rad slices. See :class:`CocipGrid`.
+    met : MetDataset
+        CoCiP met slices. See :class:`CocipGrid`.
+    rad : MetDataset | None, optional
+        CoCiP rad slices. If ``keys`` is not None, this parameter must be None.
     dz_m : float | None, optional
         Difference in altitude between top and bottom layer for stratification calculations (m).
         Must be specified if ``keys`` is None.
     humidity_scaling : humidity_scaling.HumidityScaling | None, optional
         Specific humidity scaling scheme. Must be specified if ``keys`` is None.
-    keys : list[str]
+    keys : Sequence[str] | None, optional
         Only run interpolators for select keys from ``met``
     **interp_kwargs : Any
         Interpolation keyword arguments
@@ -1067,8 +1074,10 @@ def _evolve_vector(
     ----------
     vector : GeoVectorDataset
         Contrail points that have been initialized and are ready for evolution.
-    met, rad : MetDataset
-        CoCiP met and rad slices. See :class:`CocipGrid`.
+    met : MetDataset
+        CoCiP met slices. See :class:`CocipGrid`.
+    rad : MetDataset
+        CoCiP rad slices. See :class:`CocipGrid`.
     params : dict[str, Any]
         CoCiP model parameters. See :class:`CocipGrid`.
     t : np.datetime64
@@ -1124,8 +1133,10 @@ def _run_downwash(
     ----------
     vector : GeoVectorDataset
         Grid values
-    met, rad : MetDataset
-        CoCiP met and rad slices. See :class:`CocipGrid`.
+    met : MetDataset
+        CoCiP met slices. See :class:`CocipGrid`.
+    rad : MetDataset
+        CoCiP rad slices. See :class:`CocipGrid`.
     params : dict[str, Any]
         CoCiP model parameters. See :class:`CocipGrid`.
 
@@ -1297,6 +1308,8 @@ def find_initial_contrail_regions(
     # which is why we compute it here
     T_crit_sac = sac.T_critical_sac(t_sat_liq[filt], rh[filt], G[filt])
     filtered_vector["T_crit_sac"] = T_crit_sac
+    if params["vpm_activation"]:
+        filtered_vector["G"] = G[filt]  # only used in vpm_activation
     return filtered_vector, pd.Series(data=sac_, index=vector["index"])
 
 
@@ -1487,14 +1500,29 @@ def find_initial_persistent_contrails(
         air_pressure_1=air_pressure_1,
     )
     iwc_1 = contrail_properties.iwc_post_wake_vortex(iwc, iwc_ad)
-    f_surv = contrail_properties.ice_particle_survival_fraction(iwc, iwc_1)
+
+    if params["vpm_activation"]:
+        # We can add a Cocip parameter for T_exhaust, vpm_ei_n, and particles
+        aei = extended_k15.droplet_apparent_emission_index(
+            specific_humidity=specific_humidity,
+            T_ambient=air_temperature,
+            T_exhaust=vector.attrs.get("T_exhaust", extended_k15.DEFAULT_EXHAUST_T),
+            air_pressure=air_pressure,
+            nvpm_ei_n=nvpm_ei_n,
+            vpm_ei_n=vector.attrs.get("vpm_ei_n", extended_k15.DEFAULT_VPM_EI_N),
+            G=vector["G"],
+        )
+        min_aei = None
+    else:
+        f_activ = contrail_properties.ice_particle_activation_rate(air_temperature, T_crit_sac)
+        aei = nvpm_ei_n * f_activ
+        min_aei = params["min_ice_particle_number_nvpm_ei_n"]
+
     n_ice_per_m_0 = contrail_properties.initial_ice_particle_number(
-        nvpm_ei_n=nvpm_ei_n,
-        fuel_dist=fuel_dist,
-        air_temperature=air_temperature,
-        T_crit_sac=T_crit_sac,
-        min_ice_particle_number_nvpm_ei_n=params["min_ice_particle_number_nvpm_ei_n"],
+        aei=aei, fuel_dist=fuel_dist, min_aei=min_aei
     )
+
+    f_surv = contrail_properties.ice_particle_survival_fraction(iwc, iwc_1)
     n_ice_per_m_1 = n_ice_per_m_0 * f_surv
 
     # The logic below corresponds to Cocip._create_downwash_contrail (roughly)
@@ -2131,7 +2159,7 @@ def result_to_metdataset(
     result : VectorDataset | None
         Aggregated data arising from contrail evolution. Expected to contain keys:
         ``index``, ``age``, ``ef``.
-    verbose_dict : dict[str, npt.NDArray[np.floating]]:
+    verbose_dict : dict[str, npt.NDArray[np.floating]]
         Verbose outputs to attach to results.
     source : MetDataset
         :attr:`CocipGrid.`source` data on which to attach results.
@@ -2366,11 +2394,11 @@ def _check_coverage(
 
     Parameters
     ----------
-    met_array : np.ndarray
+    met_array : npt.NDArray[_T]
         Coordinate on met data
-    grid_array : np.ndarray
+    grid_array : npt.NDArray[_T]
         Coordinate on grid data
-    coord : {"longitude", "latitude", "level", "time"}
+    coord : str
         Name of coordinate. Only used for warning message.
     name : str
         Name of met dataset. Only used for warning message.

pycontrails/models/dry_advection.py

@@ -137,14 +137,14 @@ class DryAdvection(models.Model):
 
         Parameters
         ----------
-        source : GeoVectorDataset
+        source : GeoVectorDataset | None
             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
+        **params : Any
             Overwrite model parameters defined in ``__init__``.
 
         Returns