pycontrails 0.49.5__cp310-cp310-win_amd64.whl → 0.50.1__cp310-cp310-win_amd64.whl

pycontrails/datalib/goes.py

@@ -50,7 +50,7 @@ except ModuleNotFoundError as exc:
 
 
 #: Default channels to use if none are specified. These are the channels
-#: required by the MIT ash color scheme.
+#: required by the SEVIRI (MIT) ash color scheme.
 DEFAULT_CHANNELS = "C11", "C14", "C15"
 
 #: The time at which the GOES scan mode changed from mode 3 to mode 6. This
@@ -203,10 +203,10 @@ def gcs_goes_path(
         GOES Region of interest.
     channels : str | Iterable[str]
         Set of channels or bands for CMIP data. The 16 possible channels are
-        represented by the strings "C01" to "C16". For the MIT ash color scheme,
+        represented by the strings "C01" to "C16". For the SEVIRI ash color scheme,
         set ``channels=("C11", "C14", "C15")``. For the true color scheme,
         set ``channels=("C01", "C02", "C03")``. By default, the channels
-        required by the MIT ash color scheme are used.
+        required by the SEVIRI ash color scheme are used.
 
     Returns
     -------
@@ -306,10 +306,10 @@ class GOES:
 
     channels : str | set[str] | None
         Set of channels or bands for CMIP data. The 16 possible channels are
-        represented by the strings "C01" to "C16". For the MIT ash color scheme,
+        represented by the strings "C01" to "C16". For the SEVIRI ash color scheme,
         set ``channels=("C11", "C14", "C15")``. For the true color scheme,
         set ``channels=("C01", "C02", "C03")``. By default, the channels
-        required by the MIT ash color scheme are used. The channels must have
+        required by the SEVIRI ash color scheme are used. The channels must have
         a common horizontal resolution. The resolutions are:
 
         - C01: 1.0 km
@@ -585,7 +585,7 @@ def _concat_c02(ds1: XArrayType, ds2: XArrayType) -> XArrayType:
 def extract_goes_visualization(
     da: xr.DataArray,
     color_scheme: str = "ash",
-    ash_convention: str = "MIT",
+    ash_convention: str = "SEVIRI",
     gamma: float = 2.2,
 ) -> tuple[npt.NDArray[np.float32], ccrs.Geostationary, tuple[float, float, float, float]]:
     """Extract artifacts for visualizing GOES data with the given color scheme.
@@ -597,7 +597,7 @@ def extract_goes_visualization(
         required by :func:`to_ash`.
     color_scheme : str = {"ash", "true"}
         Color scheme to use for visualization.
-    ash_convention : str = {"MIT", "standard"}
+    ash_convention : str = {"SEVIRI", "standard"}
         Passed into :func:`to_ash`. Only used if ``color_scheme="ash"``.
     gamma : float = 2.2
         Passed into :func:`to_true_color`. Only used if ``color_scheme="true"``.
@@ -672,17 +672,18 @@ def to_true_color(da: xr.DataArray, gamma: float = 2.2) -> npt.NDArray[np.float3
     return np.dstack([red, green, blue])
 
 
-def to_ash(da: xr.DataArray, convention: str = "MIT") -> npt.NDArray[np.float32]:
+def to_ash(da: xr.DataArray, convention: str = "SEVIRI") -> npt.NDArray[np.float32]:
     """Compute 3d RGB array for the ASH color scheme.
 
     Parameters
     ----------
     da : xr.DataArray
         DataArray of GOES data with appropriate channels.
-    convention : str = {"MIT", "standard"}
+    convention : str = {"SEVIRI", "standard"}
         Convention for color space.
 
-        - MIT convention requires channels C11, C14, C15
+        - SEVIRI convention requires channels C11, C14, C15.
+          Used in :cite:`kulikSatellitebasedDetectionContrails2019`.
         - Standard convention requires channels C11, C13, C14, C15
 
     Returns
@@ -693,6 +694,7 @@ def to_ash(da: xr.DataArray, convention: str = "MIT") -> npt.NDArray[np.float32]
     References
     ----------
     - `Ash RGB quick guide (the color space and color interpretations) <https://rammb.cira.colostate.edu/training/visit/quick_guides/GOES_Ash_RGB.pdf>`_
+    - :cite:`SEVIRIRGBCal`
     - :cite:`kulikSatellitebasedDetectionContrails2019`
 
     Examples
@@ -716,7 +718,7 @@ def to_ash(da: xr.DataArray, convention: str = "MIT") -> npt.NDArray[np.float32]
         green = c14 - c11
         blue = c13
 
-    elif convention == "MIT":
+    elif convention in ["SEVIRI", "MIT"]:  # retain MIT for backwards compatibility
         c11 = da.sel(band_id=11).values  # 8.44
         c14 = da.sel(band_id=14).values  # 11.19
         c15 = da.sel(band_id=15).values  # 12.27
@@ -726,7 +728,7 @@ def to_ash(da: xr.DataArray, convention: str = "MIT") -> npt.NDArray[np.float32]
         blue = c14
 
     else:
-        raise ValueError("Convention must be either 'MIT' or 'standard'")
+        raise ValueError("Convention must be either 'SEVIRI' or 'standard'")
 
     # See colostate pdf for slightly wider values
     red = _clip_and_scale(red, -4.0, 2.0)

pycontrails/models/cocip/cocip.py

@@ -26,12 +26,13 @@ from pycontrails.models.cocip import (
     contrail_properties,
     radiative_forcing,
     radiative_heating,
+    unterstrasser_wake_vortex,
     wake_vortex,
     wind_shear,
 )
 from pycontrails.models.cocip.cocip_params import CocipFlightParams
 from pycontrails.models.emissions.emissions import Emissions
-from pycontrails.physics import geo, thermo, units
+from pycontrails.physics import constants, geo, thermo, units
 
 logger = logging.getLogger(__name__)
 
@@ -534,10 +535,11 @@ class Cocip(Model):
             self.source.size,
         )
         if not intersection.any():
-            raise ValueError(
+            msg = (
                 "No intersection between flight waypoints and met domain. "
-                "Rerun Cocip with `met` overlapping flight."
+                "Rerun Cocip with met overlapping flight."
             )
+            raise ValueError(msg)
 
         # STEP 4: Begin met interpolation
         # Unfortunately we use both "u_wind" and "eastward_wind" to refer to the
@@ -837,9 +839,9 @@ class Cocip(Model):
         T_critical_sac = self._sac_flight["T_critical_sac"]
 
         # Flight performance parameters
-        fuel_dist = (
-            self._sac_flight.get_data_or_attr("fuel_flow") / self._sac_flight["true_airspeed"]
-        )
+        fuel_flow = self._sac_flight.get_data_or_attr("fuel_flow")
+        true_airspeed = self._sac_flight["true_airspeed"]
+        fuel_dist = fuel_flow / true_airspeed
 
         nvpm_ei_n = self._sac_flight.get_data_or_attr("nvpm_ei_n")
         ei_h2o = self._sac_flight.fuel.ei_h2o
@@ -889,11 +891,27 @@ class Cocip(Model):
             air_temperature, air_pressure, air_pressure_1
         )
         iwc_1 = contrail_properties.iwc_post_wake_vortex(iwc, iwc_ad)
+
+        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)
+            f_surv = unterstrasser_wake_vortex.ice_particle_number_survival_fraction(
+                air_temperature,
+                rhi_0,
+                ei_h2o,
+                wingspan,
+                true_airspeed,
+                fuel_flow,
+                nvpm_ei_n,
+                0.5 * depth,  # Taking the mid-point of the contrail plume
+            )
+        else:
+            f_surv = contrail_properties.ice_particle_survival_fraction(iwc, iwc_1)
+
         n_ice_per_m_1 = contrail_properties.ice_particle_number(
             nvpm_ei_n=nvpm_ei_n,
             fuel_dist=fuel_dist,
-            iwc=iwc,
-            iwc_1=iwc_1,
+            f_surv=f_surv,
             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"],
@@ -1101,6 +1119,9 @@ class Cocip(Model):
 
         # Initially set energy forcing to 0 because the contrail just formed (age = 0)
         contrail["ef"] = np.zeros_like(contrail["n_ice_per_m"])
+        if self.params["compute_atr20"]:
+            contrail["global_yearly_mean_rf"] = np.zeros_like(contrail["n_ice_per_m"])
+            contrail["atr20"] = np.zeros_like(contrail["n_ice_per_m"])
 
         if not self.params["filter_sac"]:
             contrail["sac"] = self._downwash_flight["sac"]
@@ -1226,6 +1247,10 @@ class Cocip(Model):
 
         # Perform all aggregations
         agg_dict = {"ef": ["sum"], "age": ["max"]}
+        if self.params["compute_atr20"]:
+            agg_dict["global_yearly_mean_rf"] = ["sum"]
+            agg_dict["atr20"] = ["sum"]
+
         rad_keys = ["sdr", "rsr", "olr", "rf_sw", "rf_lw", "rf_net"]
         for key in rad_keys:
             if self.params["verbose_outputs"]:
@@ -1236,6 +1261,10 @@ class Cocip(Model):
         aggregated = grouped.agg(agg_dict)
         aggregated.columns = [f"{k1}_{k2}" for k1, k2 in aggregated.columns]
         aggregated = aggregated.rename(columns={"ef_sum": "ef", "age_max": "contrail_age"})
+        if self.params["compute_atr20"]:
+            aggregated = aggregated.rename(
+                columns={"global_yearly_mean_rf_sum": "global_yearly_mean_rf", "atr20_sum": "atr20"}
+            )
 
         # Join the two
         df = df.join(aggregated)
@@ -2372,6 +2401,14 @@ def calc_timestep_contrail_evolution(
     contrail_2["ef"] = energy_forcing_2
     contrail_2["age"][energy_forcing_2 == 0.0] = np.timedelta64(0, "ns")
 
+    if params["compute_atr20"]:
+        contrail_2["global_yearly_mean_rf"] = (
+            contrail_2["ef"] / constants.surface_area_earth / constants.seconds_per_year
+        )
+        contrail_2["atr20"] = (
+            params["global_rf_to_atr20_factor"] * contrail_2["global_yearly_mean_rf"]
+        )
+
     # filter contrail_2 by persistent waypoints, if any continuous segments are left
     logger.debug(
         "Fraction of waypoints surviving: %s / %s",
@@ -2408,6 +2445,9 @@ def calc_timestep_contrail_evolution(
         continuous = final_contrail["continuous"]
         final_contrail["ef"][~continuous] = 0.0
         final_contrail["age"][~continuous] = np.timedelta64(0, "ns")
+        if params["compute_atr20"]:
+            final_contrail["global_yearly_mean_rf"][~continuous] = 0.0
+            final_contrail["atr20"][~continuous] = 0.0
     return final_contrail
 
 

pycontrails/models/cocip/cocip_params.py

@@ -102,7 +102,7 @@ class CocipParams(ModelParams):
     met_latitude_buffer: tuple[float, float] = (10.0, 10.0)
 
     #: Met level buffer [:math:`hPa`] for Cocip initialization and evolution.
-    met_level_buffer: tuple[float, float] = (200.0, 200.0)
+    met_level_buffer: tuple[float, float] = (40.0, 40.0)
 
     # ---------
     # Filtering
@@ -136,6 +136,16 @@ class CocipParams(ModelParams):
     #: :attr:`CocipGridParams.verbose_outputs_evolution`.
     verbose_outputs: bool = False
 
+    #: Add additional metric of ATR20 and global yearly mean RF to model output.
+    #: These are not standard CoCiP outputs but based on the derivation used
+    #: in the first supplement to :cite:`yinPredictingClimateImpact2023`. ATR20 is defined
+    #: as the average temperature response over a 20 year horizon.
+    compute_atr20: bool = False
+
+    #: Constant factor used to convert global- and year-mean RF, [:math:`W m^{-2}`],
+    #: to ATR20, [:math:`K`], given by :cite:`yinPredictingClimateImpact2023`.
+    global_rf_to_atr20_factor: float = 0.0151
+
     # ----------------
     # Model parameters
     # ----------------
@@ -174,6 +184,15 @@ class CocipParams(ModelParams):
     #: :attr:`radiative_heating_effects` is enabled.
     max_depth: float = 1500.0
 
+    #: Experimental. Improved ice crystal number survival fraction in the wake vortex phase.
+    #: Implement :cite:`unterstrasserPropertiesYoungContrails2016`, who developed a
+    #: parametric model that estimates the survival fraction of the contrail ice crystal
+    #: number after the wake vortex phase based on the results from large eddy simulations.
+    #: This replicates Fig. 4 of :cite:`karcherFormationRadiativeForcing2018`.
+    #:
+    #:  .. versionadded:: 0.50.1
+    unterstrasser_ice_survival_fraction: bool = False
+
     #: Experimental. Radiative heating effects on contrail cirrus properties.
     #: Terrestrial and solar radiances warm the contrail ice particles and cause
     #: convective turbulence. This effect is expected to enhance vertical mixing

pycontrails/models/cocip/contrail_properties.py

@@ -204,8 +204,7 @@ def iwc_post_wake_vortex(
 def ice_particle_number(
     nvpm_ei_n: npt.NDArray[np.float64],
     fuel_dist: npt.NDArray[np.float64],
-    iwc: npt.NDArray[np.float64],
-    iwc_1: npt.NDArray[np.float64],
+    f_surv: npt.NDArray[np.float64],
     air_temperature: npt.NDArray[np.float64],
     T_crit_sac: npt.NDArray[np.float64],
     min_ice_particle_number_nvpm_ei_n: float,
@@ -223,11 +222,8 @@ def ice_particle_number(
         black carbon number emissions index, [:math:`kg^{-1}`]
     fuel_dist : npt.NDArray[np.float64]
         fuel consumption of the flight segment per distance traveled, [:math:`kg m^{-1}`]
-    iwc : npt.NDArray[np.float64]
-        initial ice water content at each flight waypoint before the wake vortex
-        phase, [:math:`kg_{H_{2}O}/kg_{air}`]
-    iwc_1 : npt.NDArray[np.float64]
-        ice water content after the wake vortex phase, [:math:`kg_{H_{2}O}/kg_{air}`]
+    f_surv : npt.NDArray[np.float64]
+        Fraction of contrail ice particle number that survive the wake vortex phase.
     air_temperature : npt.NDArray[np.float64]
         ambient temperature for each waypoint, [:math:`K`]
     T_crit_sac : npt.NDArray[np.float64]
@@ -241,7 +237,6 @@ def ice_particle_number(
     npt.NDArray[np.float64]
         initial number of ice particles per distance after the wake vortex phase, [:math:`# m^{-1}`]
     """
-    f_surv = ice_particle_survival_factor(iwc, iwc_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) * f_surv
@@ -289,7 +284,7 @@ def ice_particle_activation_rate(
     return -0.661 * np.exp(d_temp) + 1.0
 
 
-def ice_particle_survival_factor(
+def ice_particle_survival_fraction(
     iwc: npt.NDArray[np.float64], iwc_1: npt.NDArray[np.float64]
 ) -> npt.NDArray[np.float64]:
     """