cloudnetpy 1.70.2__py3-none-any.whl → 1.71.1__py3-none-any.whl

cloudnetpy/plotting/plot_meta.py

@@ -588,5 +588,10 @@ ATTRIBUTES = {
         "lwp": PlotMeta(
             zero_line=True,
         ),
+        "epsilon": PlotMeta(
+            cmap="inferno",
+            plot_range=(1e-7, 1e-1),
+            log_scale=True,
+        ),
     },
 }

cloudnetpy/products/epsilon.py

@@ -0,0 +1,202 @@
+from os import PathLike
+from pathlib import Path
+
+import doppy
+import doppy.netcdf
+import netCDF4
+import numpy as np
+import numpy.typing as npt
+import scipy.constants
+from doppy.product.turbulence import HorizontalWind, Options, Turbulence, VerticalWind
+from scipy.interpolate import LinearNDInterpolator, NearestNDInterpolator
+
+import cloudnetpy
+from cloudnetpy.output import copy_variables
+from cloudnetpy.utils import get_time, get_uuid
+
+
+def generate_epsilon_from_lidar(
+    doppler_lidar_file: str | PathLike,
+    doppler_lidar_wind_file: str | PathLike,
+    output_file: str | PathLike,
+    uuid: str | None,
+):
+    sliding_window_in_seconds = 3 * 60
+    uuid = uuid if uuid is not None else get_uuid()
+    opts = _get_options(doppler_lidar_file)
+    opts.period = sliding_window_in_seconds
+    vert = _vertical_wind_from_doppler_lidar_file(doppler_lidar_file)
+    hori = _horizontal_wind_from_doppler_lidar_file(doppler_lidar_wind_file)
+    turb = Turbulence.from_winds(vert, hori, opts)
+
+    with (
+        netCDF4.Dataset(Path(doppler_lidar_file), "r") as nc_src,
+        doppy.netcdf.Dataset(Path(output_file), format="NETCDF4_CLASSIC") as nc,
+    ):
+        nc.add_dimension("time")
+        nc.add_dimension("height", size=len(turb.height))
+        nc.add_time(
+            name="time",
+            dimensions=("time",),
+            standard_name="time",
+            long_name="Time UTC",
+            data=turb.time,
+            dtype="f8",
+        )
+        nc.add_variable(
+            name="height",
+            dimensions=("height",),
+            units="m",
+            data=turb.height,
+            standard_name=nc_src["height"].standard_name,
+            long_name=nc_src["height"].long_name,
+            dtype="f4",
+        )
+        nc.add_variable(
+            name="epsilon",
+            dimensions=("time", "height"),
+            units="m2 s-3",
+            data=turb.turbulent_kinetic_energy_dissipation_rate,
+            mask=turb.mask,
+            dtype="f4",
+            long_name="Dissipation rate of turbulent kinetic energy",
+        )
+        nc.add_scalar_variable(
+            name="ray_accumulation_time",
+            units="s",
+            long_name="Ray accumulation time",
+            data=opts.ray_accumulation_time,
+            dtype="f4",
+        )
+        nc.add_scalar_variable(
+            name="rolling_window_period",
+            units="s",
+            long_name="Rolling window period",
+            data=opts.period,
+            dtype="f4",
+        )
+
+        nc.add_attribute("file_uuid", uuid)
+        nc.add_attribute("cloudnet_file_type", "epsilon-lidar")
+        nc.add_attribute("doppy_version", doppy.__version__)
+        nc.add_attribute("cloudnetpy_version", cloudnetpy.__version__)
+        nc.add_attribute(
+            "title",
+            "Dissipation rate of turbulent kinetic energy (lidar) "
+            f"from {nc_src.location}",
+        )
+
+    copy_attributes_from_src(doppler_lidar_file, output_file)
+
+    with (
+        netCDF4.Dataset(output_file, "r+") as nc_out,
+        netCDF4.Dataset(doppler_lidar_file, "r") as nc_src_stare,
+        netCDF4.Dataset(doppler_lidar_wind_file, "r") as nc_src_wind,
+    ):
+        copy_variables(
+            nc_src_stare, nc_out, ("latitude", "longitude", "altitude", "source")
+        )
+        nc_out.source_file_uuids = f"{nc_src_stare.file_uuid}, {nc_src_wind.file_uuid}"
+        sources = {nc_src_stare.source, nc_src_wind.source}
+        nc_out.source = ", ".join(sources)
+        history = (
+            f"{get_time()} - epsilon-lidar file created using doppy "
+            f"v{doppy.__version__} and cloudnetpy v{cloudnetpy.__version__}\n"
+            f"{nc_src_stare.history}\n"
+            f"{nc_src_wind.history}"
+        )
+        history = "\n".join(
+            line.strip() for line in history.splitlines() if line.strip()
+        )
+        nc_out.history = history
+        nc_out.references = "https://doi.org/10.1175/2010JTECHA1455.1"
+    return uuid
+
+
+def copy_attributes_from_src(src: str | PathLike, trg: str | PathLike) -> None:
+    with netCDF4.Dataset(src, "r") as nc_src, netCDF4.Dataset(trg, "a") as nc_trg:
+        for attr in ("year", "month", "day", "location", "Conventions"):
+            nc_trg.setncattr(attr, nc_src.getncattr(attr))
+
+
+def _horizontal_wind_from_doppler_lidar_file(
+    doppler_lidar_wind_file: str | PathLike,
+) -> HorizontalWind:
+    with netCDF4.Dataset(doppler_lidar_wind_file, "r") as nc:
+        time = _datetime64_from_nc_var(nc["time"])
+        height = np.array(nc["height"][:].data, dtype=np.float64)
+        uwind = np.array(nc["uwind"][:].data, dtype=np.float64)
+        vwind = np.array(nc["vwind"][:].data, dtype=np.float64)
+        umask = np.array(nc["uwind"][:].mask, dtype=np.bool_)
+        vmask = np.array(nc["vwind"][:].mask, dtype=np.bool_)
+        V = np.sqrt(uwind**2 + vwind**2)
+        mask = umask | vmask
+        t = np.broadcast_to(time[:, None], mask.shape)[~mask]
+        h = np.broadcast_to(height[None, :], mask.shape)[~mask]
+        interp_linear = LinearNDInterpolator(list(zip(t, h, strict=False)), V[~mask])
+        interp_nearest = NearestNDInterpolator(list(zip(t, h, strict=False)), V[~mask])
+        T, H = np.meshgrid(time, height, indexing="ij")
+        V_linear = interp_linear(T, H)
+        V_nearest = interp_nearest(T, H)
+        isnan = np.isnan(V_linear)
+        V_interp = V_linear
+        V_interp[isnan] = V_nearest[isnan]
+        if np.isnan(V_interp).any():
+            msg = "Unexpected nans"
+            raise ValueError(msg)
+        return HorizontalWind(time=time, height=height, V=V_interp)
+
+
+def _get_options(doppler_lidar_file: str | PathLike) -> Options:
+    with netCDF4.Dataset(doppler_lidar_file, "r") as nc:
+        if "ray_accumulation_time" in nc.variables:
+            return Options(ray_accumulation_time=nc["ray_accumulation_time"][:])
+        if "pulses_per_ray" in nc.variables:
+            prf = _infer_pulse_repetition_frequency(
+                np.array(nc["range"][:].data, dtype=np.float64)
+            )
+            return Options(ray_accumulation_time=float(nc["pulses_per_ray"][:] / prf))
+        msg = "Missing ray info"
+        raise ValueError(msg)
+
+
+def _infer_pulse_repetition_frequency(range_: npt.NDArray[np.float64]):
+    c = scipy.constants.c
+    dist = range_.max() - range_.min()
+    round_trip_time = 2 * dist / c
+
+    T_LOW = 1 / 10_000  # Halo XR instruments operate on lower frequency
+    T_HIGH = 1 / 15_000  # Rest should operate on higher frequency
+    if round_trip_time / T_HIGH < 1:
+        return 15e3
+    if round_trip_time / T_LOW < 1:
+        return 10e3
+    msg = f"Suspiciously large range ({dist}m). " "Cannot infer pulse repetition rate"
+    raise ValueError(msg)
+
+
+def _vertical_wind_from_doppler_lidar_file(
+    doppler_lidar_file: str | PathLike,
+) -> VerticalWind:
+    with netCDF4.Dataset(doppler_lidar_file, "r") as nc:
+        time = _datetime64_from_nc_var(nc["time"])
+        height = np.array(nc["height"][:].data, dtype=np.float64)
+        w = np.array(nc["v"][:].data, dtype=np.float64)
+        mask = np.array(nc["v"][:].mask, dtype=np.bool_)
+    if isinstance(mask, np.ndarray) and mask.any():
+        w[mask] = np.nan
+
+    return VerticalWind(time=time, height=height, w=w, mask=mask)
+
+
+def _datetime64_from_nc_var(var: netCDF4.Variable) -> npt.NDArray[np.datetime64]:
+    return np.array(
+        netCDF4.num2date(
+            var[:].data,
+            units=var.units,
+            calendar=var.calendar,
+            only_use_cftime_datetimes=False,
+            only_use_python_datetimes=True,
+        ),
+        dtype="datetime64[us]",
+    )

cloudnetpy/version.py

@@ -1,4 +1,4 @@
 MAJOR = 1
-MINOR = 70
-PATCH = 2
+MINOR = 71
+PATCH = 1
 __version__ = f"{MAJOR}.{MINOR}.{PATCH}"

{cloudnetpy-1.70.2.dist-info → cloudnetpy-1.71.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: cloudnetpy
-Version: 1.70.2
+Version: 1.71.1
 Summary: Python package for Cloudnet processing
 Author: Simo Tukiainen
 License: MIT License
@@ -42,6 +42,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cloudnetpy_qc>=1.15.0
+Requires-Dist: doppy>=0.5.0
 Requires-Dist: matplotlib
 Requires-Dist: mwrpy>=1.2.0
 Requires-Dist: netCDF4

{cloudnetpy-1.70.2.dist-info → cloudnetpy-1.71.1.dist-info}/RECORD

@@ -9,7 +9,7 @@ cloudnetpy/metadata.py,sha256=BDEpgwZ58PHznc1gi11gtNNV4kFiMAmlHnF4huTy7nw,5982
 cloudnetpy/output.py,sha256=lq4YSeMT_d-j4rlQkKm9KIZ8boupTBBBKV1eUawpmCI,15672
 cloudnetpy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cloudnetpy/utils.py,sha256=U0iMIKPiKLrLVAfs_u9pPuoWYW1RJHcM8dbLF9a4yIA,29796
-cloudnetpy/version.py,sha256=ZJmkQTWA_9Ao_G9kBNB4TdpjcMG9CP6xNuk_jl8SpBw,72
+cloudnetpy/version.py,sha256=Jpj6HUmEXjg2ZHK10S2ho3h_9Khi4cQ_qHcHcBrM7AU,72
 cloudnetpy/categorize/__init__.py,sha256=s-SJaysvVpVVo5kidiruWQO6p3gv2TXwY1wEHYO5D6I,44
 cloudnetpy/categorize/atmos_utils.py,sha256=RcmbKxm2COkE7WEya0mK3yX5rzUbrewRVh3ekm01RtM,10598
 cloudnetpy/categorize/attenuation.py,sha256=Y_-fzmQTltWTqIZTulJhovC7a6ifpMcaAazDJcnMIOc,990
@@ -101,7 +101,7 @@ cloudnetpy/model_evaluation/tests/unit/test_plotting.py,sha256=h9V8JKmrO4v9bOvv-
 cloudnetpy/model_evaluation/tests/unit/test_statistical_methods.py,sha256=Ra3r4V0qbqkpDuaTYvEIbaasl0nZ5gmTLR4eGC0glBQ,9724
 cloudnetpy/model_evaluation/tests/unit/test_tools.py,sha256=Ia_VrLdV2NstX5gbx_3AZTOAlrgLAy_xFZ8fHYVX0xI,3817
 cloudnetpy/plotting/__init__.py,sha256=lg9Smn4BI0dVBgnDLC3JVJ4GmwoSnO-qoSd4ApvwV6Y,107
-cloudnetpy/plotting/plot_meta.py,sha256=RTGpvXXcCUawLasAeiAaCvNxfeUyf9Cd_1nG77kxv5A,17257
+cloudnetpy/plotting/plot_meta.py,sha256=qfyZJNis937uM-NJseer8i4FO7I_v5jhQPyFl5Uszi8,17390
 cloudnetpy/plotting/plotting.py,sha256=Hi_n3TjzqR2KjZgalFHGxsb7jTsqub9nWzZyscfk6xA,38385
 cloudnetpy/products/__init__.py,sha256=2hRb5HG9hNrxH1if5laJkLeFeaZCd5W1q3hh4ewsX0E,273
 cloudnetpy/products/classification.py,sha256=KwAiBSgFwDqhM114NIgYiUjj8HoYc7gAlc8E1QgcSig,8207
@@ -109,6 +109,7 @@ cloudnetpy/products/der.py,sha256=soypE7uSEP4uHUCCQVEhyXsKY6e9mzV9B_2S5GUizqk,12
 cloudnetpy/products/drizzle.py,sha256=58C9Mo6oRXR8KpbVPghbJvHvFX9GfS3xUp058pbf0qw,10804
 cloudnetpy/products/drizzle_error.py,sha256=4GwlHRtNbk9ks7bGtXCco-wXbcDOKeAQwKmbhzut6Qk,6132
 cloudnetpy/products/drizzle_tools.py,sha256=HLxUQ89mFNo6IIe6Cj3ZH-TPkJdpMxKCOt4cOOmcLs0,11002
+cloudnetpy/products/epsilon.py,sha256=fthijjUAa7bEhoObRiTOGr4_uRgCpXSfqxIOPD2NGT4,7617
 cloudnetpy/products/ier.py,sha256=70jyYrhO-kAHuQ3CpDVcyKKuHT3c9Eby6ADHHlPjAFY,5986
 cloudnetpy/products/iwc.py,sha256=FQtYFYnMNuDnjuK1ee3zOfzPtKsoWH95CXtEz1iplZI,9462
 cloudnetpy/products/lwc.py,sha256=sl6Al2tuH3KkCBrPbWTmuz3jlD5UQJ4D6qBsn1tt2CQ,18962
@@ -116,9 +117,9 @@ cloudnetpy/products/mie_lu_tables.nc,sha256=It4fYpqJXlqOgL8jeZ-PxGzP08PMrELIDVe5
 cloudnetpy/products/mwr_tools.py,sha256=rd7UC67O4fsIE5SaHVZ4qWvUJTj41ZGwgQWPwZzOM14,5377
 cloudnetpy/products/product_tools.py,sha256=uu4l6reuGbPcW3TgttbaSrqIKbyYGhBVTdnC7opKvmg,11101
 docs/source/conf.py,sha256=IKiFWw6xhUd8NrCg0q7l596Ck1d61XWeVjIFHVSG9Og,1490
-cloudnetpy-1.70.2.dist-info/LICENSE,sha256=wcZF72bdaoG9XugpyE95Juo7lBQOwLuTKBOhhtANZMM,1094
-cloudnetpy-1.70.2.dist-info/METADATA,sha256=3uZXezdrr0wokIJ1UEEAHOb0olG14cgknYFO14RcKlw,5844
-cloudnetpy-1.70.2.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
-cloudnetpy-1.70.2.dist-info/entry_points.txt,sha256=HhY7LwCFk4qFgDlXx_Fy983ZTd831WlhtdPIzV-Y3dY,51
-cloudnetpy-1.70.2.dist-info/top_level.txt,sha256=ibSPWRr6ojS1i11rtBFz2_gkIe68mggj7aeswYfaOo0,16
-cloudnetpy-1.70.2.dist-info/RECORD,,
+cloudnetpy-1.71.1.dist-info/LICENSE,sha256=wcZF72bdaoG9XugpyE95Juo7lBQOwLuTKBOhhtANZMM,1094
+cloudnetpy-1.71.1.dist-info/METADATA,sha256=-4IIIVCrDs5UmXIrXQmlWzZ-Q9sV5SVodXEjgh_kdqc,5872
+cloudnetpy-1.71.1.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
+cloudnetpy-1.71.1.dist-info/entry_points.txt,sha256=HhY7LwCFk4qFgDlXx_Fy983ZTd831WlhtdPIzV-Y3dY,51
+cloudnetpy-1.71.1.dist-info/top_level.txt,sha256=ibSPWRr6ojS1i11rtBFz2_gkIe68mggj7aeswYfaOo0,16
+cloudnetpy-1.71.1.dist-info/RECORD,,