disdrodb 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

disdrodb/physics/atmosphere.py

@@ -0,0 +1,272 @@
+# -----------------------------------------------------------------------------.
+# Copyright (c) 2021-2026 DISDRODB developers
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# -----------------------------------------------------------------------------.
+"""DISDRODB atmospheric physics module."""
+import numpy as np
+import xarray as xr
+
+
+def get_gravitational_acceleration(latitude, altitude=0):
+    """
+    Computes gravitational acceleration at a given altitude and latitude.
+
+    Parameters
+    ----------
+    altitude : float
+        Altitude in meters. The default is 0 m (sea level).
+    latitude : float
+        Latitude in degrees.
+
+    Returns
+    -------
+    float
+        Gravitational acceleration in m/s^2.
+    """
+    g0 = 9.806229 - 0.025889372 * np.cos(2 * np.deg2rad(latitude))
+    return g0 - 2.879513 * altitude / 1e6
+
+
+def get_air_pressure_at_height(
+    altitude,
+    latitude,
+    temperature,
+    sea_level_air_pressure=101_325,
+    lapse_rate=0.0065,
+    gas_constant_dry_air=287.04,
+):
+    """
+    Computes the air pressure at a given height in a standard atmosphere.
+
+    According to the hypsometric formula of Brutsaert 1982; Ulaby et al. 1981
+
+    Parameters
+    ----------
+    altitude : float
+        Altitude in meters.
+    latitude : float
+        Latitude in degrees.
+    temperature : float
+        Temperature at altitude in Kelvin.
+    sea_level_air_pressure : float, optional
+        Standard atmospheric pressure at sea level in Pascals. The default is 101_325 Pascals.
+    lapse_rate : float, optional
+        Standard atmospheric lapse rate in K/m. The default is 0.0065 K/m.
+    gas_constant_dry_air : float, optional
+        Gas constant for dry air in J/(kg*K). The default is 287.04 J/(kg*K).
+
+    Returns
+    -------
+    float
+        Air pressure in Pascals.
+    """
+    g = get_gravitational_acceleration(altitude=altitude, latitude=latitude)
+    return sea_level_air_pressure * np.exp(
+        -g / (lapse_rate * gas_constant_dry_air) * np.log(1 + lapse_rate * altitude / temperature),
+    )
+
+
+def get_air_temperature_at_height(altitude, sea_level_temperature, lapse_rate=0.0065):
+    """
+    Computes the air temperature at a given height in a standard atmosphere.
+
+    Reference: Brutsaert 1982; Ulaby et al. 1981
+
+    Parameters
+    ----------
+    altitude : float
+        Altitude in meters.
+    sea_level_temperature : float
+        Standard temperature at sea level in Kelvin.
+    lapse_rate : float, optional
+        Standard atmospheric lapse rate in K/m. The default is 0.0065 K/m.
+
+    Returns
+    -------
+    float
+        Air temperature in Kelvin.
+    """
+    return sea_level_temperature - lapse_rate * altitude
+
+
+def get_air_dynamic_viscosity(temperature):
+    """
+    Computes the dynamic viscosity of dry air.
+
+    Reference: Beard 1977; Pruppacher & Klett 1978
+
+    Parameters
+    ----------
+    temperature : float
+        Temperature in Kelvin.
+
+    Returns
+    -------
+    float
+        Dynamic viscosity of dry air in kg/(m*s) (aka Pa*s).
+    """
+    # Convert to Celsius
+    temperature = temperature - 273.15
+
+    # Define mask
+    above_freezing_mask = temperature > 0
+
+    # Compute viscosity above freezing temperature
+    viscosity_above_0 = (1.721 + 0.00487 * temperature) / 1e5
+
+    # Compute viscosity below freezing temperature
+    viscosity_below_0 = (1.718 + 0.0049 * temperature - 1.2 * temperature**2 / 1e5) / 1e5
+
+    # Define final viscosity
+    viscosity = xr.where(above_freezing_mask, viscosity_above_0, viscosity_below_0)
+    return viscosity
+
+
+def get_air_density(temperature, air_pressure, vapor_pressure, gas_constant_dry_air=287.04):
+    """
+    Computes the air density according to the equation of state for moist air.
+
+    Reference: Brutsaert 1982
+
+    Parameters
+    ----------
+    temperature : float
+        Temperature in Kelvin.
+    air_pressure : float
+        Air pressure in Pascals.
+    vapor_pressure : float
+        Vapor pressure in Pascals.
+    gas_constant_dry_air : float, optional
+        Gas constant for dry air in J/(kg*K). The default is 287.04 J/(kg*K).
+
+    Returns
+    -------
+    float
+        Air density in kg/m^3.
+    """
+    # # Define constant for water vapor in J/(kg·K)
+    # gas_constant_water_vapor=461.5
+
+    # # Partial pressure of dry air (Pa)
+    # pressure_dry_air = air_pressure - vapor_pressure
+
+    # # Density of dry air (kg/m^3)
+    # density_dry_air = pressure_dry_air / (gas_constant_dry_air * temperature)
+
+    # # Density of water vapor (kg/m^3)
+    # density_water_vapor = vapor_pressure / (gas_constant_water_vapor * temperature)
+
+    # # Total air density (kg/m^3)
+    # air_density = density_dry_air + density_water_vapor
+
+    return air_pressure * (1 - 0.378 * vapor_pressure / air_pressure) / (gas_constant_dry_air * temperature)
+
+
+def get_vapor_actual_pressure_at_height(
+    altitude,
+    sea_level_temperature,
+    sea_level_relative_humidity,
+    sea_level_air_pressure=101_325,
+    lapse_rate=0.0065,
+):
+    """
+    Computes the vapor pressure using Yamamoto's exponential relationship.
+
+    Reference: Brutsaert 1982
+
+    Parameters
+    ----------
+    altitude : float
+        Altitude in meters.
+    sea_level_temperature : float
+        Standard temperature at sea level in Kelvin.
+    sea_level_relative_humidity : float
+        Relative humidity at sea level. A value between 0 and 1.
+    sea_level_air_pressure : float, optional
+        Standard atmospheric pressure at sea level in Pascals. The default is 101_325 Pascals.
+    lapse_rate : float, optional
+        Standard atmospheric lapse rate in K/m. The default is 0.0065 K/m.
+
+    Returns
+    -------
+    float
+        Vapor pressure in Pascals.
+    """
+    temperature_at_altitude = get_air_temperature_at_height(
+        altitude=altitude,
+        sea_level_temperature=sea_level_temperature,
+        lapse_rate=lapse_rate,
+    )
+    esat = get_vapor_saturation_pressure(sea_level_temperature)
+    actual_vapor = sea_level_relative_humidity / (1 / esat - (1 - sea_level_relative_humidity) / sea_level_air_pressure)
+    return actual_vapor * np.exp(-(5.8e3 * lapse_rate / (temperature_at_altitude**2) + 5.5e-5) * altitude)
+
+
+def get_vapor_saturation_pressure(temperature):
+    """
+    Computes the saturation vapor pressure over water as a function of temperature.
+
+    Use formulation and coefficients of Wexler (1976, 1977).
+    References: Brutsaert 1982; Pruppacher & Klett 1978; Flatau & al. 1992
+
+    Parameters
+    ----------
+    temperature : float
+        Temperature in Kelvin.
+
+    Returns
+    -------
+    float
+        Saturation vapor pressure in Pascal.
+    """
+    # Polynomial coefficients
+    g = [
+        -0.29912729e4,
+        -0.60170128e4,
+        0.1887643854e2,
+        -0.28354721e-1,
+        0.17838301e-4,
+        -0.84150417e-9,
+        0.44412543e-12,
+        0.2858487e1,
+    ]
+    # Perform polynomial accumulation using Horner rule
+    esat = g[6]
+    for i in [5, 4, 3, 2]:
+        esat = esat * temperature + g[i]
+    esat = esat + g[7] * np.log(temperature)
+    for i in [1, 0]:
+        esat = esat * temperature + g[i]
+    return np.exp(esat / (temperature**2))
+
+
+def get_vapor_actual_pressure(relative_humidity, temperature):
+    """
+    Computes the actual vapor pressure over water.
+
+    Parameters
+    ----------
+    relative_humidity : float
+        Relative humidity. A value between 0 and 1.
+    temperature : float
+        Temperature in Kelvin.
+
+    Returns
+    -------
+    float
+        Actual vapor pressure in Pascal.
+    """
+    esat = get_vapor_saturation_pressure(temperature)
+    return relative_humidity * esat

disdrodb/physics/water.py

@@ -0,0 +1,130 @@
+# -----------------------------------------------------------------------------.
+# Copyright (c) 2021-2026 DISDRODB developers
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# -----------------------------------------------------------------------------.
+"""DISDRODB water physics module."""
+import numpy as np
+import xarray as xr
+
+
+def get_pure_water_density(temperature):
+    """
+    Computes the density of pure water at standard pressure.
+
+    For temperatures above freezing uses Kell formulation.
+    For temperatures below freezing use Dorsch & Boyd formulation.
+
+    References: Pruppacher & Klett 1978; Weast & Astle 1980
+
+    Parameters
+    ----------
+    temperature : float
+        Temperature in Kelvin.
+
+    Returns
+    -------
+    float
+        Density of pure water in kg/m^3.
+    """
+    # Convert to Celsius
+    temperature = temperature - 273.15
+
+    # Define mask
+    above_freezing_mask = temperature > 0
+
+    # Compute density above freezing temperature
+    c = [9.9983952e2, 1.6945176e1, -7.9870401e-3, -4.6170461e-5, 1.0556302e-7, -2.8054253e-10, 1.6879850e-2]
+    density = c[0] + sum(c * temperature**i for i, c in enumerate(c[1:6], start=1))
+    density_above_0 = density / (1 + c[6] * temperature)
+
+    # Compute density below freezing temperature
+    c = [999.84, 0.086, -0.0108]
+    density_below_0 = c[0] + sum(c * temperature**i for i, c in enumerate(c[1:], start=1))
+
+    # Define final density
+    density = xr.where(above_freezing_mask, density_above_0, density_below_0)
+    return density
+
+
+def get_pure_water_compressibility(temperature):
+    """
+    Computes the isothermal compressibility of pure ordinary water.
+
+    Reference: Kell, Weast & Astle 1980
+
+    Parameters
+    ----------
+    temperature : float
+        Temperature in Kelvin.
+
+    Returns
+    -------
+    float
+        Compressibility of water in Pascals.
+    """
+    # Convert to Celsius
+    temperature = temperature - 273.15
+
+    # Compute compressibility
+    c = [5.088496e1, 6.163813e-1, 1.459187e-3, 2.008438e-5, -5.857727e-8, 4.10411e-10, 1.967348e-2]
+    compressibility = c[0] + sum(c * temperature**i for i, c in enumerate(c[1:6], start=1))
+    compressibility = compressibility / (1 + c[6] * temperature) * 1e-11
+    return compressibility
+
+
+def get_pure_water_surface_tension(temperature):
+    """
+    Computes the surface tension of pure ordinary water against air.
+
+    Reference: Pruppacher & Klett 1978
+
+    Parameters
+    ----------
+    temperature : float
+        Temperature in Kelvin.
+
+    Returns
+    -------
+    float
+        Surface tension in N/m.
+    """
+    sigma = 0.0761 - 0.000155 * (temperature - 273.15)
+    return sigma
+
+
+def get_water_density(temperature, air_pressure, sea_level_air_pressure=101_325):
+    """
+    Computes the density of water according to Weast & Astle 1980.
+
+    Parameters
+    ----------
+    temperature : float
+        Temperature in Kelvin.
+    air_pressure : float
+        Air pressure in Pascals.
+    sea_level_air_pressure : float
+        Standard atmospheric pressure at sea level in Pascals.
+        The default is 101_325 Pascal.
+    freezing_temperature : float, optional
+        Freezing temperature of water in Kelvin. The default is 273.15 K.
+
+    Returns
+    -------
+    float
+        Water density in kg/m^3.
+    """
+    delta_pressure = sea_level_air_pressure - air_pressure
+    water_compressibility = get_pure_water_compressibility(temperature)
+    return get_pure_water_density(temperature) * np.exp(-1 * water_compressibility * delta_pressure)

disdrodb/physics/wrappers.py

@@ -0,0 +1,62 @@
+# -----------------------------------------------------------------------------.
+# Copyright (c) 2021-2026 DISDRODB developers
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# -----------------------------------------------------------------------------.
+"""DISDRODB physics wrapper functions."""
+from disdrodb.physics.atmosphere import (
+    get_air_density,
+    get_air_dynamic_viscosity,
+    get_air_pressure_at_height,
+    get_vapor_actual_pressure,
+)
+
+
+####---------------------------------------------------------------------------.
+#### Wrappers
+def retrieve_air_pressure(ds_env):
+    """Retrieve air pressure."""
+    if "air_pressure" in ds_env:
+        return ds_env["air_pressure"]
+    air_pressure = get_air_pressure_at_height(
+        altitude=ds_env["altitude"],
+        latitude=ds_env["latitude"],
+        temperature=ds_env["temperature"],
+        sea_level_air_pressure=ds_env["sea_level_air_pressure"],
+        lapse_rate=ds_env["lapse_rate"],
+    )
+    return air_pressure
+
+
+def retrieve_air_dynamic_viscosity(ds_env):
+    """Retrieve air dynamic viscosity."""
+    air_viscosity = get_air_dynamic_viscosity(ds_env["temperature"])
+    return air_viscosity
+
+
+def retrieve_air_density(ds_env):
+    """Retrieve air density."""
+    temperature = ds_env["temperature"]
+    relative_humidity = ds_env["relative_humidity"]
+    air_pressure = retrieve_air_pressure(ds_env)
+    vapor_pressure = get_vapor_actual_pressure(
+        relative_humidity=relative_humidity,
+        temperature=temperature,
+    )
+    air_density = get_air_density(
+        temperature=temperature,
+        air_pressure=air_pressure,
+        vapor_pressure=vapor_pressure,
+    )
+    return air_density

disdrodb/psd/__init__.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------.
-# Copyright (c) 2021-2023 DISDRODB developers
+# Copyright (c) 2021-2026 DISDRODB developers
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

disdrodb/psd/fitting.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------.
-# Copyright (c) 2021-2023 DISDRODB developers
+# Copyright (c) 2021-2026 DISDRODB developers
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -23,7 +23,7 @@ from scipy.optimize import minimize
 from scipy.special import gamma, gammaln  # Regularized lower incomplete gamma function
 
 from disdrodb.constants import DIAMETER_DIMENSION
-from disdrodb.l1.fall_velocity import get_raindrop_fall_velocity_from_ds
+from disdrodb.fall_velocity import get_rain_fall_velocity_from_ds
 from disdrodb.l2.empirical_dsd import (
     get_median_volume_drop_diameter,
     get_moment,
@@ -1056,14 +1056,26 @@ def _compute_z(ND, D, dD):
     return Z
 
 
-def _compute_target_variable_error(target, ND_obs, ND_preds, D, dD, V):
+def _compute_target_variable_error(target, ND_obs, ND_preds, D, dD, V, relative=False, eps=1e-12):
+    # Compute observed and predicted target variables
     if target == "Z":
-        errors = np.abs(_compute_z(ND_obs, D, dD) - _compute_z(ND_preds, D, dD))
+        obs = _compute_z(ND_obs, D, dD)
+        pred = _compute_z(ND_preds, D, dD)
     elif target == "R":
-        errors = np.abs(_compute_rain_rate(ND_obs, D, dD, V) - _compute_rain_rate(ND_preds, D, dD, V))
-    else:  # if target == "LWC":
-        errors = np.abs(_compute_lwc(ND_obs, D, dD) - _compute_lwc(ND_preds, D, dD))
-    return errors
+        obs = _compute_rain_rate(ND_obs, D, dD, V)
+        pred = _compute_rain_rate(ND_preds, D, dD, V)
+    else:  # "LWC"
+        obs = _compute_lwc(ND_obs, D, dD)
+        pred = _compute_lwc(ND_preds, D, dD)
+
+    # Absolute error
+    abs_error = np.abs(obs - pred)
+
+    # Return relative error if requested
+    if relative:
+        return abs_error / (np.abs(obs) + eps)
+
+    return abs_error
 
 
 def _compute_cost_function(ND_obs, ND_preds, D, dD, V, target, transformation, error_order):
@@ -1992,6 +2004,7 @@ ATTRS_PARAMS_DICT = {
     },
 }
 
+PSD_MODELS = list(ATTRS_PARAMS_DICT)
 
 MOM_METHODS_DICT = {
     "GammaPSD": {
@@ -2356,7 +2369,7 @@ def get_gs_parameters(ds, psd_model, target="ND", transformation="log", error_or
 
     # Check fall velocity is available if target R
     if "fall_velocity" not in ds:
-        ds["fall_velocity"] = get_raindrop_fall_velocity_from_ds(ds)
+        ds["fall_velocity"] = get_rain_fall_velocity_from_ds(ds)
 
     # Retrieve estimation function
     func = OPTIMIZATION_ROUTINES_DICT["GS"][psd_model]

disdrodb/psd/models.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------.
-# Copyright (c) 2021-2023 DISDRODB developers
+# Copyright (c) 2021-2026 DISDRODB developers
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

disdrodb/routines/__init__.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------.
-# Copyright (c) 2021-2023 DISDRODB developers
+# Copyright (c) 2021-2026 DISDRODB developers
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -18,6 +18,7 @@
 from disdrodb.routines.wrappers import (
     create_summary,
     create_summary_station,
+    run,
     run_l0,
     run_l0_station,
     run_l0a,
@@ -32,11 +33,13 @@ from disdrodb.routines.wrappers import (
     run_l2e_station,
     run_l2m,
     run_l2m_station,
+    run_station,
 )
 
 __all__ = [
     "create_summary",
     "create_summary_station",
+    "run",
     "run_l0",
     "run_l0_station",
     "run_l0a",
@@ -51,4 +54,5 @@ __all__ = [
     "run_l2e_station",
     "run_l2m",
     "run_l2m_station",
+    "run_station",
 ]

disdrodb/routines/l0.py

@@ -1,7 +1,5 @@
-#!/usr/bin/env python3
-
 # -----------------------------------------------------------------------------.
-# Copyright (c) 2021-2023 DISDRODB developers
+# Copyright (c) 2021-2026 DISDRODB developers
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -50,6 +48,7 @@ from disdrodb.l0.l0b_nc_processing import sanitize_ds
 from disdrodb.l0.l0b_processing import generate_l0b
 from disdrodb.l0.l0c_processing import TOLERANCE_SECONDS, create_l0c_datasets
 from disdrodb.metadata import read_station_metadata
+from disdrodb.routines.options import L0CProcessingOptions
 from disdrodb.utils.archiving import group_files_by_time_block
 from disdrodb.utils.dask import execute_tasks_safely
 from disdrodb.utils.decorators import delayed_if_parallel, single_threaded_if_parallel
@@ -329,6 +328,7 @@ def _generate_l0c(
     # Processing info
     metadata,
     # Processing options
+    folder_partitioning,
     force,
     verbose,
     parallel,  # this is used only to initialize the correct logger !
@@ -336,8 +336,6 @@ def _generate_l0c(
     """Define L0C product processing."""
     # Define product
     product = "L0C"
-    # Define folder partitioning
-    folder_partitioning = get_folder_partitioning()
 
     # Define product processing function
     def core(
@@ -873,15 +871,6 @@ def run_l0c_station(
         station_name=station_name,
     )
 
-    # -----------------------------------------------------------------.
-    # Retrieve metadata
-    metadata = read_station_metadata(
-        metadata_archive_dir=metadata_archive_dir,
-        data_source=data_source,
-        campaign_name=campaign_name,
-        station_name=station_name,
-    )
-
     # ------------------------------------------------------------------------.
     # Start processing
     t_i = time.time()
@@ -925,10 +914,30 @@ def run_l0c_station(
     if filepaths is None:
         return
 
+    # -----------------------------------------------------------------.
+    # Read station metadata and sensor name
+    metadata = read_station_metadata(
+        metadata_archive_dir=metadata_archive_dir,
+        data_source=data_source,
+        campaign_name=campaign_name,
+        station_name=station_name,
+    )
+    sensor_name = metadata["sensor_name"]
+
+    # -------------------------------------------------------------------------.
+    # Retrieve L0C processing options
+    l0c_processing_options = L0CProcessingOptions(sensor_name=sensor_name)
+    product_frequency = l0c_processing_options.product_frequency
+    folder_partitioning = l0c_processing_options.folder_partitioning
+
     # -------------------------------------------------------------------------.
     # Retrieve dictionary with the required files per time block
-    # TODO: allow customizing this in config file, but risk of out of memory !
-    list_event_info = group_files_by_time_block(filepaths=filepaths, freq="day", tolerance_seconds=TOLERANCE_SECONDS)
+    # - Default is "day". If "month", risk of going out of memory on small laptops
+    list_event_info = group_files_by_time_block(
+        filepaths=filepaths,
+        freq=product_frequency,
+        tolerance_seconds=TOLERANCE_SECONDS,
+    )
 
     # -----------------------------------------------------------------.
     # Generate L0C files
@@ -941,6 +950,7 @@ def run_l0c_station(
             data_dir=data_dir,
             logs_dir=logs_dir,
             logs_filename=event_info["start_time"].strftime("%Y%m%dT%H%M%S"),
+            folder_partitioning=folder_partitioning,
             # Processing options
             force=force,
             verbose=verbose,