PM-JPL 1.4.0__tar.gz → 1.5.1__tar.gz

{pm_jpl-1.4.0 → pm_jpl-1.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PM-JPL
-Version: 1.4.0
+Version: 1.5.1
 Summary: JPL implementation of the MOD16 evapotranspiration algorithm for high resolution instantaneous remote sensing imagery
 Author-email: Gregory Halverson <gregory.h.halverson@jpl.nasa.gov>, Qiaozhen Mu <qiaozhen@ntsg.umt.edu>, Maosheng Zhao <zhao@ntsg.umt.edu>, "Steven W. Running" <swr@ntsg.umt.edu>, "Claire S. Villanueva-Weeks" <claire.s.villanueva-weeks@jpl.gov>
 Project-URL: Homepage, https://github.com/JPL-Evapotranspiration-Algorithms/PM-JPL
@@ -9,18 +9,24 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: carlson-fractional-vegetation-cover
+Requires-Dist: carlson-leaf-area-index
 Requires-Dist: check-distribution
+Requires-Dist: daily-evapotranspiration-upscaling
 Requires-Dist: ECOv002-CMR>=1.0.5
 Requires-Dist: ECOv002-granules>=1.0.3
 Requires-Dist: ECOv003-granules
 Requires-Dist: GEOS5FP>=1.1.1
 Requires-Dist: MCD12C1_2019_v006
+Requires-Dist: meteorology-conversion
 Requires-Dist: NASADEM
 Requires-Dist: numpy
 Requires-Dist: pandas
+Requires-Dist: priestley-taylor
+Requires-Dist: PTJPL>=1.5.1
 Requires-Dist: rasters>=1.4.6
 Requires-Dist: SEBAL-soil-heat-flux
-Requires-Dist: sun-angles
+Requires-Dist: sun-angles>=1.3.0
 Requires-Dist: verma-net-radiation
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"

{pm_jpl-1.4.0 → pm_jpl-1.5.1}/PMJPL/PMJPL.py

@@ -17,33 +17,37 @@ from rasters import Raster, RasterGrid, RasterGeometry
 from check_distribution import check_distribution
 from GEOS5FP import GEOS5FP
 from NASADEM import NASADEM
-from verma_net_radiation import process_verma_net_radiation
+from verma_net_radiation import verma_net_radiation
 from SEBAL_soil_heat_flux import calculate_SEBAL_soil_heat_flux
 from MCD12C1_2019_v006 import load_MCD12C1_IGBP
 
-from .parameters import MOD16_parameter_from_IGBP
-from .evapotranspiration_conversion.evapotranspiration_conversion import lambda_Jkg_from_Ta_C
-from .meteorology_conversion.meteorology_conversion import SVP_Pa_from_Ta_C, calculate_specific_heat, \
-    calculate_surface_pressure, celcius_to_kelvin
-from .penman_monteith.penman_monteith import calculate_gamma
-from .priestley_taylor.priestley_taylor import delta_Pa_from_Ta_C
+from carlson_leaf_area_index import carlson_leaf_area_index
+from carlson_fractional_vegetation_cover import carlson_fractional_vegetation_cover
+from carlson_leaf_area_index import carlson_leaf_area_index
 
-from .meteorology_conversion import calculate_specific_humidity, calculate_air_density
-from .vegetation_conversion.vegetation_conversion import FVC_from_NDVI, LAI_from_NDVI
+from daily_evapotranspiration_upscaling import lambda_Jkg_from_Ta_C
 
-from .constants import *
+from meteorology_conversion import SVP_Pa_from_Ta_C
+from meteorology_conversion import calculate_air_density
+from meteorology_conversion import calculate_specific_heat
+from meteorology_conversion import calculate_specific_humidity
+from meteorology_conversion import calculate_surface_pressure
+from meteorology_conversion import celcius_to_kelvin
+
+from priestley_taylor import delta_Pa_from_Ta_C
+from PTJPL import calculate_relative_surface_wetness
+from PTJPL import RH_THRESHOLD, MIN_FWET
 
-from .fwet import calculate_fwet
+from .constants import *
+from .parameters import MOD16_parameter_from_IGBP
+from .calculate_gamma import calculate_gamma
 from .soil_moisture_constraint import calculate_fSM
 from .tmin_factor import calculate_tmin_factor
-from .correctance_factor import calculate_rcorr
+from .correctance_factor import calculate_correctance_factor
 from .VPD_factor import calculate_VPD_factor
-
 from .canopy_conductance import calculate_canopy_conductance
-
 from .wet_canopy_resistance import calculate_wet_canopy_resistance
-from .canopy_aerodynamic_resistance import calculate_rtotc
-
+from .canopy_aerodynamic_resistance import calculate_canopy_aerodynamic_resistance
 from .wet_soil_evaporation import calculate_wet_soil_evaporation
 from .potential_soil_evaporation import calculate_potential_soil_evaporation
 from .interception import calculate_interception
@@ -65,7 +69,6 @@ DEFAULT_OUTPUT_VARIABLES = [
     'ET_daily_kg'
 ]
 
-
 def PMJPL(
         NDVI: Union[Raster, np.ndarray],
         ST_C: Union[Raster, np.ndarray] = None,
@@ -86,7 +89,9 @@ def PMJPL(
         elevation_km: Union[Raster, np.ndarray] = None,
         delta_Pa: Union[Raster, np.ndarray] = None,
         lambda_Jkg: Union[Raster, np.ndarray] = None,
-        gamma_Jkg: Union[Raster, np.ndarray, float] = None) -> Dict[str, Raster]:
+        gamma_Jkg: Union[Raster, np.ndarray, float] = None,
+        RH_threshold: float = RH_THRESHOLD,
+        min_fwet: float = MIN_FWET) -> Dict[str, Raster]:
     results = {}
 
     if geometry is None and isinstance(NDVI, Raster):
@@ -143,7 +148,7 @@ def PMJPL(
                 resampling=resampling
             )
 
-        Rn_results = process_verma_net_radiation(
+        Rn_results = verma_net_radiation(
             SWin=SWin,
             albedo=albedo,
             ST_C=ST_C,
@@ -170,12 +175,12 @@ def PMJPL(
     
     results["G"] = G
 
-    LAI = LAI_from_NDVI(NDVI)
+    LAI = carlson_leaf_area_index(NDVI)
 
     # calculate fraction of vegetation cover if it's not given
     if FVC is None:
         # calculate fraction of vegetation cover from NDVI
-        FVC = FVC_from_NDVI(NDVI)
+        FVC = carlson_fractional_vegetation_cover(NDVI)
 
     # calculate surface air pressure if it's not given
     if Ps_Pa is None:
@@ -241,7 +246,12 @@ def PMJPL(
 
     # calculate relative surface wetness (fwet)
     # from relative humidity
-    fwet = calculate_fwet(RH)
+    fwet = calculate_relative_surface_wetness(
+        RH=RH,
+        RH_threshold=RH_threshold,
+        min_fwet=min_fwet
+    )
+    
     results['fwet'] = fwet
 
     logger.info("calculating PM-MOD resistances")
@@ -307,7 +317,7 @@ def PMJPL(
     # calculate correctance factor (rcorr)
     # for stomatal and cuticular conductances
     # from surface pressure and air temperature
-    rcorr = calculate_rcorr(Ps_Pa, Ta_K)
+    rcorr = calculate_correctance_factor(Ps_Pa, Ta_K)
     results['rcorr'] = rcorr
 
     # query biome-specific mean potential stomatal conductance per unit leaf area
@@ -411,21 +421,22 @@ def PMJPL(
     # soil evaporation
 
     # query aerodynamic resistant constraints from land-cover
-    rbl_max = MOD16_parameter_from_IGBP(
+    RBL_max = MOD16_parameter_from_IGBP(
         variable="rbl_max",
         IGBP=IGBP
     )
 
-    results['rbl_max'] = rbl_max
+    results['rbl_max'] = RBL_max
 
-    rbl_min = MOD16_parameter_from_IGBP(
+    RBL_min = MOD16_parameter_from_IGBP(
         variable="rbl_min",
         IGBP=IGBP
     )
 
-    results['rbl_min'] = rbl_min
+    results['rbl_min'] = RBL_min
 
-    rtotc = calculate_rtotc(VPD_Pa, VPD_open, VPD_close, rbl_max, rbl_min)
+    # calculate canopy aerodynamic resistance in seconds per meter
+    rtotc = calculate_canopy_aerodynamic_resistance(VPD_Pa, VPD_open, VPD_close, RBL_max, RBL_min)
     results['rtotc'] = rtotc
 
     # calculate total aerodynamic resistance

pm_jpl-1.5.1/PMJPL/__init__.py

@@ -0,0 +1,4 @@
+from .PMJPL import *
+from .version import __version__
+
+__author__ = "Gregory H. Halverson"

pm_jpl-1.5.1/PMJPL/calculate_gamma.py

@@ -0,0 +1,128 @@
+from typing import Union
+import numpy as np
+
+from daily_evapotranspiration_upscaling import lambda_Jkg_from_Ta_C
+
+from rasters import Raster
+
+SPECIFIC_HEAT_CAPACITY_AIR = 1013 # J kg-1 K-1, Monteith & Unsworth (2001)
+MOL_WEIGHT_WET_DRY_RATIO_AIR = 0.622
+
+def calculate_gamma(
+        Ta_C: Union[Raster, np.ndarray],
+        Ps_Pa: Union[Raster, np.ndarray],
+        Cp_Jkg: Union[Raster, np.ndarray, float] = SPECIFIC_HEAT_CAPACITY_AIR,
+        RMW: Union[Raster, np.ndarray, float] = MOL_WEIGHT_WET_DRY_RATIO_AIR) -> Union[Raster, np.ndarray]:
+    """
+    Calculate the psychrometric constant (gamma) for evapotranspiration modeling.
+    
+    The psychrometric constant is a fundamental parameter in atmospheric physics that
+    quantifies the relationship between sensible and latent heat transfer in the atmosphere.
+    It is essential for the Penman-Monteith equation and other evapotranspiration models,
+    representing the ratio of specific heat of moist air to the latent heat of vaporization
+    multiplied by the ratio of molecular weights of water vapor to dry air.
+    
+    Mathematical Formula:
+    γ = (Cp × P) / (λ × ε)
+    
+    Where:
+    - γ = psychrometric constant (Pa K⁻¹)
+    - Cp = specific heat capacity of air at constant pressure (J kg⁻¹ K⁻¹)
+    - P = atmospheric pressure (Pa)
+    - λ = latent heat of vaporization of water (J kg⁻¹)
+    - ε = ratio of molecular weight of water vapor to dry air (≈ 0.622)
+    
+    Physical Significance:
+    The psychrometric constant is temperature and pressure dependent, making it crucial
+    for accurate evapotranspiration calculations across diverse environmental conditions.
+    It accounts for:
+    - Temperature effects on latent heat of vaporization (Clausius-Clapeyron relation)
+    - Elevation effects through atmospheric pressure variations
+    - Energy partitioning between sensible and latent heat fluxes
+    
+    This implementation is part of the MOD16 evapotranspiration algorithm used by
+    NASA's ECOSTRESS mission and is designed for processing high-resolution remote
+    sensing imagery.
+    
+    Parameters
+    ----------
+    Ta_C : Union[Raster, np.ndarray]
+        Air temperature in degrees Celsius. Used to calculate the temperature-dependent
+        latent heat of vaporization through the Clausius-Clapeyron equation.
+        
+    Ps_Pa : Union[Raster, np.ndarray]
+        Surface atmospheric pressure in Pascals. Accounts for elevation effects on
+        evapotranspiration rates. Lower pressure at higher elevations reduces the
+        psychrometric constant.
+        
+    Cp_Jkg : Union[Raster, np.ndarray, float], optional
+        Specific heat capacity of air at constant pressure in J kg⁻¹ K⁻¹.
+        Default: 1013 J kg⁻¹ K⁻¹ (Monteith & Unsworth, 2001).
+        This represents the amount of energy required to raise the temperature
+        of 1 kg of air by 1 K at constant pressure.
+        
+    RMW : Union[Raster, np.ndarray, float], optional
+        Ratio of molecular weights of water vapor to dry air (dimensionless).
+        Default: 0.622 (18.016 g/mol ÷ 28.97 g/mol).
+        This constant accounts for the different molecular masses affecting
+        vapor pressure relationships.
+    
+    Returns
+    -------
+    Union[Raster, np.ndarray]
+        Psychrometric constant in Pa K⁻¹. Values typically range from 60-70 Pa K⁻¹
+        at sea level and standard temperature, increasing with elevation and
+        decreasing with temperature.
+    
+    Notes
+    -----
+    The psychrometric constant is used extensively in:
+    - Penman-Monteith equation for reference evapotranspiration
+    - Energy balance calculations for partitioning available energy
+    - Vapor pressure deficit relationships for atmospheric moisture demand
+    - Canopy conductance models for transpiration calculations
+    
+    The temperature dependency through λ(T) is critical because:
+    - Higher temperatures decrease latent heat of vaporization
+    - This affects evapotranspiration rates and energy partitioning
+    - Accurate temperature relationships are essential for global applications
+    
+    References
+    ----------
+    .. [1] Monteith, J. L., & Unsworth, M. H. (2001). Principles of Environmental 
+           Physics (3rd ed.). Academic Press.
+    .. [2] Mu, Q., Zhao, M., & Running, S. W. (2011). Improvements to a MODIS 
+           global terrestrial evapotranspiration algorithm. Remote Sensing of 
+           Environment, 115(8), 1781-1800. doi:10.1016/j.rse.2011.02.019
+    .. [3] Allen, R. G., Pereira, L. S., Raes, D., & Smith, M. (1998). Crop 
+           evapotranspiration - Guidelines for computing crop water requirements. 
+           FAO Irrigation and drainage paper 56.
+    .. [4] Penman, H. L. (1948). Natural evaporation from open water, bare soil 
+           and grass. Proceedings of the Royal Society of London, 193(1032), 120-145.
+    
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from rasters import Raster
+    >>> 
+    >>> # Calculate gamma for standard conditions
+    >>> Ta_C = np.array([20.0, 25.0, 30.0])  # Air temperature in Celsius
+    >>> Ps_Pa = np.array([101325, 101325, 101325])  # Sea level pressure
+    >>> gamma = calculate_gamma(Ta_C, Ps_Pa)
+    >>> print(f"Psychrometric constant: {gamma} Pa K⁻¹")
+    >>> 
+    >>> # For high elevation (lower pressure)
+    >>> Ps_Pa_high = np.array([85000, 85000, 85000])  # ~1500m elevation
+    >>> gamma_high = calculate_gamma(Ta_C, Ps_Pa_high)
+    >>> print(f"High elevation gamma: {gamma_high} Pa K⁻¹")
+    
+    See Also
+    --------
+    lambda_Jkg_from_Ta_C : Calculate latent heat of vaporization from temperature
+    delta_Pa_from_Ta_C : Calculate slope of saturation vapor pressure curve
+    """
+    # calculate latent heat of vaporization (J kg-1)
+    lambda_Jkg = lambda_Jkg_from_Ta_C(Ta_C)
+    gamma =  (Cp_Jkg * Ps_Pa) / (lambda_Jkg * RMW)
+    
+    return gamma

pm_jpl-1.5.1/PMJPL/canopy_aerodynamic_resistance.py

@@ -0,0 +1,164 @@
+from typing import Union
+import numpy as np
+import rasters as rt
+from rasters import Raster
+
+def calculate_canopy_aerodynamic_resistance(
+    VPD_Pa: Union[Raster, np.ndarray],
+    VPD_open_Pa: Union[Raster, np.ndarray],
+    VPD_close_Pa: Union[Raster, np.ndarray],
+    RBL_max: Union[Raster, np.ndarray],
+    RBL_min: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
+    """
+    Calculate total canopy aerodynamic resistance based on vapor pressure deficit.
+    
+    This function computes the total aerodynamic resistance to the canopy as a 
+    function of vapor pressure deficit (VPD) and biome-specific boundary layer resistance 
+    parameters. The resistance varies between minimum and maximum values based on stomatal 
+    response to atmospheric moisture demand, implementing a key component of the MOD16 
+    evapotranspiration algorithm.
+    
+    **CRITICAL**: All VPD-related parameters must be in Pascals (Pa) to ensure correct 
+    operation with MOD16 lookup table values. Using different pressure units will cause 
+    incorrect stomatal response calculations.
+    
+    The aerodynamic resistance represents the resistance to water vapor and heat transfer 
+    from the canopy to the atmosphere through the boundary layer. This parameter is crucial 
+    for accurately modeling transpiration rates and energy partitioning in vegetation.
+    
+    Physical Mechanism:
+    - At low VPD (high atmospheric humidity): Stomata remain open, resistance is maximum
+    - At high VPD (low atmospheric humidity): Stomata close to conserve water, resistance is minimum
+    - Between thresholds: Linear interpolation models gradual stomatal response
+    
+    Mathematical Implementation:
+    - VPD_Pa ≤ VPD_open_Pa: resistance = RBL_max (stomata fully open)
+    - VPD_Pa ≥ VPD_close_Pa: resistance = RBL_min (stomata mostly closed)
+    - VPD_open_Pa < VPD_Pa < VPD_close_Pa: resistance = RBL_min + (RBL_max - RBL_min) × (VPD_close_Pa - VPD_Pa) / (VPD_close_Pa - VPD_open_Pa)
+    
+    This formulation captures the physiological response of plants to atmospheric dryness,
+    where stomata progressively close as VPD increases to prevent excessive water loss,
+    thereby increasing the resistance to water vapor transfer.
+    
+    Parameters
+    ----------
+    VPD_Pa : Union[Raster, np.ndarray]
+        Vapor pressure deficit in Pascals (Pa). **UNITS ARE CRITICAL** - must be in 
+        Pascals to match MOD16 lookup table thresholds. Represents the difference 
+        between saturated and actual vapor pressure, indicating atmospheric moisture 
+        demand. Higher VPD values indicate drier atmospheric conditions that stress 
+        vegetation. Typical range: 100-5000 Pa.
+        
+        **Warning**: Using different units (e.g., kPa, hPa, or mb) will cause 
+        incorrect results since direct numerical comparisons are made against 
+        biome-specific thresholds defined in Pascals.
+        
+    VPD_open_Pa : Union[Raster, np.ndarray]
+        VPD threshold in Pascals (Pa) below which stomata are completely open and 
+        there is no water stress effect on transpiration. Biome-specific parameter 
+        from MOD16 lookup table. Typical values: 650-1000 Pa.
+        **Must be in same units as VPD_Pa parameter.**
+        
+    VPD_close_Pa : Union[Raster, np.ndarray] 
+        VPD threshold in Pascals (Pa) above which stomata are almost completely 
+        closed due to water stress. Biome-specific parameter from MOD16 lookup table.
+        Typical values: 2900-4500 Pa.
+        **Must be in same units as VPD_Pa parameter.**
+        
+    RBL_max : Union[Raster, np.ndarray]
+        Maximum atmospheric boundary layer resistance in s m⁻¹. Applied when VPD is
+        low (favorable conditions) and stomata are fully open. Biome-specific parameter
+        representing maximum resistance to vapor transfer. Typical values: 45-100 s m⁻¹.
+        
+    RBL_min : Union[Raster, np.ndarray]
+        Minimum atmospheric boundary layer resistance in s m⁻¹. Applied when VPD is
+        high (water stress conditions) and stomata are mostly closed. Biome-specific
+        parameter representing minimum resistance to vapor transfer. 
+        Typical values: 20-70 s m⁻¹.
+    
+    Returns
+    -------
+    Union[Raster, np.ndarray]
+        Total canopy aerodynamic resistance in s m⁻¹. Higher values indicate
+        greater resistance to water vapor and heat transfer from canopy to atmosphere.
+        Values range between RBL_min and RBL_max depending on VPD conditions.
+    
+    Notes
+    -----
+    The function implements a three-piece piecewise linear function that models the
+    physiological response of vegetation to atmospheric water demand:
+    
+    1. **Low VPD regime** (VPD_Pa ≤ VPD_open_Pa): Optimal conditions where stomata remain
+       fully open and resistance is at maximum, allowing efficient photosynthesis
+       with minimal water stress.
+       
+    2. **High VPD regime** (VPD_Pa ≥ VPD_close_Pa): Severe water stress conditions where
+       stomata close to conserve water, reducing resistance to minimum values and
+       limiting transpiration.
+       
+    3. **Intermediate VPD regime** (VPD_open_Pa < VPD_Pa < VPD_close_Pa): Transitional zone
+       where stomata gradually close as atmospheric demand increases, following a
+       linear relationship between the threshold values.
+    
+    This formulation is essential for:
+    - Accurate transpiration modeling under varying atmospheric conditions
+    - Energy balance calculations in land surface models
+    - Water stress assessment in vegetation monitoring
+    - Climate impact studies on ecosystem water use
+    
+    The biome-specific parameters (VPD_open_Pa, VPD_close_Pa, RBL_min, RBL_max) are derived
+    from the MOD16 lookup table based on IGBP land cover classifications, allowing
+    the model to account for different vegetation types' physiological responses.
+    
+    References
+    ----------
+    .. [1] Mu, Q., Zhao, M., & Running, S. W. (2011). Improvements to a MODIS 
+           global terrestrial evapotranspiration algorithm. Remote Sensing of 
+           Environment, 115(8), 1781-1800. doi:10.1016/j.rse.2011.02.019
+    .. [2] Mu, Q., Heinsch, F. A., Zhao, M., & Running, S. W. (2007). Development 
+           of a global evapotranspiration algorithm based on MODIS and global 
+           meteorology data. Remote Sensing of Environment, 111(4), 519-536.
+    .. [3] Monteith, J. L. (1995). A reinterpretation of stomatal responses to 
+           humidity. Plant, Cell & Environment, 18(4), 357-364.
+    .. [4] Ball, J. T., Woodrow, I. E., & Berry, J. A. (1987). A model predicting 
+           stomatal conductance and its contribution to the control of photosynthesis 
+           under different environmental conditions. Progress in Photosynthesis 
+           Research, 4, 221-224.
+    
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from rasters import Raster
+    >>> 
+    >>> # Example for grassland (IGBP class 10)
+    >>> VPD_Pa = np.array([500, 1500, 3000, 5000])  # Pa
+    >>> VPD_open_Pa = np.array([650, 650, 650, 650])  # Pa (grassland threshold)
+    >>> VPD_close_Pa = np.array([4200, 4200, 4200, 4200])  # Pa (grassland threshold)
+    >>> RBL_max = np.array([50, 50, 50, 50])  # s/m (grassland maximum)
+    >>> RBL_min = np.array([20, 20, 20, 20])  # s/m (grassland minimum)
+    >>> 
+    >>> rtotc = calculate_canopy_aerodynamic_resistance(VPD_Pa, VPD_open_Pa, VPD_close_Pa, RBL_max, RBL_min)
+    >>> print(f"Aerodynamic resistance: {rtotc} s/m")
+    >>> # Expected: [50, ~36, ~22, 20] - decreasing resistance with increasing VPD
+    >>> 
+    >>> # Demonstrate VPD stress response
+    >>> VPD_stress = np.linspace(0, 5000, 100)  # Full VPD range
+    >>> rtotc_response = calculate_canopy_aerodynamic_resistance(VPD_stress, 650, 4200, 50, 20)
+    >>> # Shows smooth transition from 50 to 20 s/m as VPD increases
+    
+    See Also
+    --------
+    MOD16_parameter_from_IGBP : Retrieve biome-specific parameters from lookup table
+    calculate_rcorr : Calculate resistance correction factor
+    calculate_VPD_factor : Calculate VPD-based stress factor
+    """
+    rtotc = rt.where(VPD_Pa <= VPD_open_Pa, RBL_max, np.nan)
+    rtotc = rt.where(VPD_Pa >= VPD_close_Pa, RBL_min, rtotc)
+
+    rtotc = rt.where(
+        np.logical_and(VPD_open_Pa < VPD_Pa, VPD_Pa < VPD_close_Pa),
+        RBL_min + (RBL_max - RBL_min) * (VPD_close_Pa - VPD_Pa) / (VPD_close_Pa - VPD_open_Pa),
+        rtotc
+    )
+
+    return rtotc

pm_jpl-1.5.1/PMJPL/canopy_conductance.py

@@ -0,0 +1,92 @@
+import numpy as np
+from typing import Union
+
+import rasters as rt
+from rasters import Raster
+
+from .constants import MAX_RESISTANCE
+
+def calculate_canopy_conductance(
+    LAI: Union[Raster, np.ndarray],
+    fwet: Union[Raster, np.ndarray],
+    gl_sh: Union[Raster, np.ndarray],
+    gs1: Union[Raster, np.ndarray],
+    Gcu: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
+    """
+    Calculate canopy conductance (Cc) to transpired water vapor per unit leaf area index (LAI).
+
+    Canopy conductance (Cc) quantifies the ease with which water vapor moves from the leaf interior,
+    through stomata and cuticle, across the leaf boundary layer, and into the atmosphere. It is a key
+    control on plant transpiration and ecosystem water fluxes, and is the inverse of surface resistance (rs)
+    in the Penman-Monteith equation for evapotranspiration.
+
+    Physical Basis:
+    - Stomatal conductance (gs1): Rate of water vapor exit through stomata, regulated by plant physiology and environment.
+    - Cuticular conductance (Gcu): Water vapor loss through the leaf cuticle, important when stomata are closed.
+    - Leaf boundary layer conductance (gl_sh): Transfer of water vapor across the thin layer of still air adjacent to the leaf surface.
+    - LAI (Leaf Area Index): Total leaf area per unit ground area, scaling conductance to the canopy level.
+    - fwet (relative surface wetness): Fraction of leaf surface that is wet, reducing transpiration when wet.
+
+    Mathematical Structure:
+    Stomatal and cuticular conductances act in parallel, and their sum is in series with the leaf boundary layer conductance:
+        Cc = gl_sh * (gs1 + Gcu) / (gs1 + gl_sh + Gcu) * LAI * (1.0 - fwet)
+    - The parallel sum: (gs1 + Gcu)
+    - The series combination: gl_sh * (gs1 + Gcu) / (gs1 + gl_sh + Gcu)
+    - Scaled by LAI and reduced by the fraction of wet surface (1 - fwet)
+    - If LAI or (1 - fwet) is zero, conductance is set to zero (no transpiration)
+    - The result is clipped to a minimum value (1/MAX_RESISTANCE) to avoid extreme/unphysical values
+
+    Parameters:
+    LAI : Union[Raster, np.ndarray]
+        Leaf area index (dimensionless). Total leaf area per unit ground area.
+    fwet : Union[Raster, np.ndarray]
+        Relative surface wetness (dimensionless, 0-1). Fraction of leaf surface that is wet.
+    gl_sh : Union[Raster, np.ndarray]
+        Leaf boundary layer conductance (m s⁻¹ LAI⁻¹).
+    gs1 : Union[Raster, np.ndarray]
+        Stomatal conductance (m s⁻¹ LAI⁻¹).
+    Gcu : Union[Raster, np.ndarray]
+        Cuticular conductance (m s⁻¹ LAI⁻¹).
+
+    Returns:
+    Union[Raster, np.ndarray]
+        Canopy conductance (Cc) to water vapor in m s⁻¹. Higher values indicate greater ease of water vapor transfer.
+
+    Notes:
+    - Canopy conductance is the inverse of surface resistance (rs) in the Penman-Monteith equation.
+    - Integrates physiological (stomatal), anatomical (cuticular), and physical (boundary layer) controls on water flux.
+    - Sensitive to environmental stress (drought, humidity, leaf wetness).
+    - If LAI or (1 - fwet) is zero, Cc is set to zero (no transpiration).
+    - Clipped to a minimum value to avoid unphysical results.
+
+    References:
+    Thornton, P. E. (1998). A mechanistic approach to modeling photosynthesis at the leaf and canopy scale. Global Change Biology, 4(4), 389-404.
+    Running, S. W., & Kimball, J. S. (2005). Remote Sensing of Terrestrial Ecosystem Processes: A Review of MODIS Algorithms. Remote Sensing of Environment, 92(1), 1-19.
+    Monteith, J. L., & Unsworth, M. H. (2001). Principles of Environmental Physics (3rd ed.). Academic Press.
+    Jarvis, P. G., & McNaughton, K. G. (1986). Stomatal control of transpiration: Scaling up from leaf to region. Advances in Ecological Research, 15, 1-49.
+
+    Example:
+        >>> import numpy as np
+        >>> LAI = np.array([2.0, 3.0])
+        >>> fwet = np.array([0.1, 0.2])
+        >>> gl_sh = np.array([0.02, 0.03])
+        >>> gs1 = np.array([0.15, 0.12])
+        >>> Gcu = np.array([0.01, 0.01])
+        >>> Cc = calculate_canopy_conductance(LAI, fwet, gl_sh, gs1, Gcu)
+        >>> print(Cc)
+    """
+    
+    # Only compute conductance where there is leaf area and the surface is not fully wet
+    Cc = rt.where(
+        np.logical_and(LAI > 0.0, (1.0 - fwet) > 0.0),
+        # Series-parallel conductance: stomatal and cuticular conductances in parallel, in series with boundary layer
+        gl_sh * (gs1 + Gcu) / (gs1 + gl_sh + Gcu) * LAI * (1.0 - fwet),
+        # If no leaf area or surface is fully wet, set conductance to zero (no transpiration)
+        0.0
+    )
+
+    # Clip conductance to a minimum value to avoid unphysical/extreme results
+    Cc = rt.clip(Cc, 1.0 / MAX_RESISTANCE, None)
+
+    # Return canopy conductance (m s^-1)
+    return Cc

{pm_jpl-1.4.0 → pm_jpl-1.5.1}/PMJPL/constants.py

@@ -1,4 +1,4 @@
-from .priestley_taylor import GAMMA_PA
+from priestley_taylor import GAMMA_PA
 
 # TODO need to defend picking arbitrary maximum to avoid extreme values
 MIN_RESISTANCE = 0.0

pm_jpl-1.5.1/PMJPL/correctance_factor.py

@@ -0,0 +1,66 @@
+from typing import Union
+import numpy as np
+import rasters as rt
+from rasters import Raster
+
+def calculate_correctance_factor(
+        Ps_Pa: Union[Raster, np.ndarray], 
+        Ta_K: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
+    """
+    Calculate the correction factor (rcorr) for stomatal and cuticular conductances
+    based on surface atmospheric pressure and air temperature.
+
+    This factor adjusts leaf conductance values from standard reference conditions
+    (sea level pressure, 20°C) to actual environmental conditions, accounting for
+    the effects of pressure and temperature on the diffusivity of water vapor in air.
+
+    Physical Basis
+    -------------
+    - Lower atmospheric pressure (e.g., high elevation) increases the diffusivity of gases, so conductance must be scaled up.
+    - Higher temperature increases molecular motion and the rate of diffusion, also requiring scaling.
+    - The correction factor ensures that modeled or measured conductances are physically consistent across different elevations and climates.
+
+    Mathematical Structure
+    ---------------------
+    The formula is:
+        rcorr = 1 / ((101300 / Ps_Pa) * (Ta_K / 293.15) ** 1.75)
+    Where:
+        Ps_Pa : surface atmospheric pressure in Pascals
+        Ta_K  : near-surface air temperature in Kelvin
+        101300: reference pressure (Pa, sea level)
+        293.15: reference temperature (K, 20°C)
+        1.75  : exponent for temperature dependence of water vapor diffusivity in air
+
+    Parameters
+    ----------
+    Ps_Pa : Union[Raster, np.ndarray]
+        Surface atmospheric pressure in Pascals (Pa).
+    Ta_K : Union[Raster, np.ndarray]
+        Near-surface air temperature in Kelvin (K).
+
+    Returns
+    -------
+    Union[Raster, np.ndarray]
+        Correction factor (rcorr), dimensionless. Used to scale stomatal and cuticular conductances to local conditions.
+
+    Notes
+    -----
+    - Used in MOD16 and similar evapotranspiration models to adjust leaf conductance parameters for local meteorological conditions.
+    - Ensures physical consistency in remote sensing and land surface models across different elevations and climates.
+    - Based on the physical principles of gas diffusion (Fick's law) and empirical temperature/pressure dependence of water vapor diffusivity.
+
+    References
+    ----------
+    Monteith, J. L., & Unsworth, M. H. (2001). Principles of Environmental Physics (3rd ed.). Academic Press.
+    Mu, Q., Zhao, M., & Running, S. W. (2011). Improvements to a MODIS global terrestrial evapotranspiration algorithm. Remote Sensing of Environment, 115(8), 1781-1800.
+    Jones, H. G. (2013). Plants and Microclimate: A Quantitative Approach to Environmental Plant Physiology (3rd ed.). Cambridge University Press.
+    Farquhar, G. D., & Sharkey, T. D. (1982). Stomatal conductance and photosynthesis. Annual Review of Plant Physiology, 33(1), 317-345.
+
+    Example
+    -------
+        >>> Ps_Pa = 90000.0  # Pa (high elevation)
+        >>> Ta_K = 303.15    # K (30°C)
+        >>> rcorr = calculate_correctance_factor(Ps_Pa, Ta_K)
+        >>> print(rcorr)
+    """
+    return 1.0 / ((101300.0 / Ps_Pa) * (Ta_K / 293.15) ** 1.75)