provide reference for sedimentation_impact_factor, update docstring u…

…nit for vertical_velocity

pycontrails/models/cocip/cocip_params.py

@@ -153,7 +153,8 @@ class CocipParams(ModelParams):
     #: Sedimentation impact factor. Denoted by :math:`f_{T}` in eq. (35) of
     #: :cite:`schumannContrailCirrusPrediction2012`.
     #: Schumann describes this as "an important adjustable parameter", and sets
-    #: it to 0.1 in the original publication.
+    #: it to 0.1 in the original publication. In :cite:`schumannAviationinducedCirrusRadiation2013`,
+    #: a value of 0.5 is referenced after comparing CoCiP predictions to observations.
     sedimentation_impact_factor: float = 0.5
 
     #: Default ``nvpm_ei_n`` value if no data provided and emissions calculations fails.

pycontrails/models/cocip/contrail_properties.py

@@ -777,7 +777,8 @@ def ice_particle_terminal_fall_speed(
 
     ``v_t`` is calculated based on a parametric model
     from :cite:`spichtingerModellingCirrusClouds2009`, using inputs of pressure
-    level, ambient temperature and the ice particle volume mean radius.
+    level, ambient temperature and the ice particle volume mean radius. See
+    Table 2 for the model parameters.
 
     Parameters
     ----------
@@ -916,11 +917,12 @@ def vertical_diffusivity(
     Accounts for the turbulence-induced diffusive contrail spreading in the vertical direction.
     See eq. (35) of :cite:`schumannContrailCirrusPrediction2012`.
 
-    The first term in Eq. (35) of Schumann (2012)
+    The first term in Eq. (35) of :cite:`schumannContrailCirrusPrediction2012` is
     (c_V * w'_N^2 / N_BV, where c_V = 0.2 and w'_N^2 = 0.1) is different
     than outlined below. Here, a constant of 0.01 is used when radiative
-    heating effects are not activated. This update comes from Schumann and
-    Graf (2013), which found that the original formulation estimated thinner
+    heating effects are not activated. This update comes from
+    :cite:`schumannAviationinducedCirrusRadiation2013`
+    , which found that the original formulation estimated thinner
     contrails relative to satellite observations. The vertical diffusivity
     was enlarged so that the simulated contrails are more consistent with observations.
     """

pycontrails/physics/geo.py

@@ -836,12 +836,12 @@ def advect_level(
     level : ArrayLike
         Pressure level, [:math:`hPa`]
     vertical_velocity : ArrayLike
-        Vertical velocity, [:math:`m s^{-1}`]
-    rho_air : ArrayLike
+        Vertical velocity, [:math:`Pa s^{-1}`]
+    rho_air : ArrayLike | float
         Air density, [:math:`kg m^{-3}`]
-    terminal_fall_speed : ArrayLike
+    terminal_fall_speed : ArrayLike | float
         Terminal fall speed of the particle, [:math:`m s^{-1}`]
-    dt : np.ndarray
+    dt : npt.NDArray[np.timedelta64] | np.timedelta64
         Time delta for each waypoint
 
     Returns
@@ -850,9 +850,9 @@ def advect_level(
         New pressure level, [:math:`hPa`]
     """
     dt_s = units.dt_to_seconds(dt, level.dtype)
-    velocity = vertical_velocity + rho_air * terminal_fall_speed * constants.g
+    dp_dt = vertical_velocity + rho_air * terminal_fall_speed * constants.g
 
-    return (level * 100.0 + (dt_s * velocity)) / 100.0
+    return (level * 100.0 + (dt_s * dp_dt)) / 100.0
 
 
 # ---------------