BESS-JPL 1.26.0__py3-none-any.whl

BESS_JPL/carbon_water_fluxes.py

@@ -0,0 +1,313 @@
+from os.path import join, abspath, dirname
+from typing import Union
+
+import numpy as np
+import rasters as rt
+from rasters import Raster, RasterGeometry
+from .C3_photosynthesis import calculate_C3_photosynthesis
+from .C4_photosynthesis import calculate_C4_photosynthesis
+from .canopy_longwave_radiation import canopy_longwave_radiation
+from .canopy_energy_balance import canopy_energy_balance
+from .soil_energy_balance import soil_energy_balance
+
+PASSES = 1
+
+def carbon_water_fluxes(
+        canopy_temperature_K: np.ndarray,  # canopy temperature in Kelvin
+        soil_temperature_K: np.ndarray,  # soil temperature in Kelvin
+        LAI: np.ndarray,  # leaf area index
+        Ta_K: np.ndarray,  # air temperature in Kelvin
+        APAR_sunlit_μmolm2s1: np.ndarray,  # sunlit leaf absorptance to photosynthetically active radiation [μmol m⁻² s⁻¹]
+        APAR_shaded_μmolm2s1: np.ndarray,  # shaded leaf absorptance to photosynthetically active radiation [μmol m⁻² s⁻¹]
+        ASW_sunlit_Wm2: np.ndarray,  # sunlit absorbed shortwave radiation [W m⁻²]
+        ASW_shaded_Wm2: np.ndarray,  # shaded absorbed shortwave radiation [W m⁻²]
+        ASW_soil_Wm2: np.ndarray,  # absorbed shortwave radiation in soil [W m⁻²]
+        Vcmax25_sunlit: np.ndarray,  # sunlit maximum carboxylation rate at 25°C [μmol m⁻² s⁻¹]
+        Vcmax25_shaded: np.ndarray,  # shaded maximum carboxylation rate at 25°C [μmol m⁻² s⁻¹]
+        ball_berry_slope: np.ndarray,  # Ball-Berry slope
+        ball_berry_intercept: Union[np.ndarray, float],  # Ball-Berry intercept
+        sunlit_fraction: np.ndarray,  # sunlit fraction of canopy
+        G_Wm2: np.ndarray,  # soil heat flux [W m⁻²]
+        SZA_deg: np.ndarray,  # solar zenith angle in degrees
+        Ca: np.ndarray,  # atmospheric CO2 concentration [μmol mol⁻¹]
+        Ps_Pa: np.ndarray,  # surface pressure [Pa]
+        gamma: np.ndarray,  # psychrometric constant [Pa K⁻¹]
+        Cp: np.ndarray,  # specific heat capacity of air [J kg⁻¹ K⁻¹]
+        rhoa: np.ndarray,  # air density [kg m⁻³]
+        VPD_Pa: np.ndarray,  # vapor pressure deficit [Pa]
+        RH: np.ndarray,  # relative humidity as a fraction
+        desTa: np.ndarray,  # 1st derivative of saturated vapor pressure [Pa K⁻¹]
+        ddesTa: np.ndarray,  # 2nd derivative of saturated vapor pressure [Pa K⁻²]
+        epsa: np.ndarray,  # clear-sky emissivity [-]
+        Rc: np.ndarray,  # canopy resistance [s m⁻¹]
+        Rs: np.ndarray,  # soil resistance [s m⁻¹]
+        carbon_uptake_efficiency: np.ndarray,  # intrinsic quantum efficiency of carbon uptake [-]
+        fStress: np.ndarray,  # stress factor [-]
+        C4_photosynthesis: bool,  # C3 or C4 photosynthesis
+        passes: int = PASSES):  # number of iterations
+    """
+    Calculate carbon and water fluxes for a canopy-soil system.
+
+    Parameters:
+        canopy_temperature_K: Canopy temperature [K].
+        soil_temperature_K: Soil temperature [K].
+        LAI: Leaf area index [-].
+        Ta_K: Air temperature [K].
+        APAR_sunlit: Sunlit leaf absorptance to photosynthetically active radiation [μmol m⁻² s⁻¹].
+        APAR_shaded: Shaded leaf absorptance to photosynthetically active radiation [μmol m⁻² s⁻¹].
+        ASW_sunlit_Wm2: Sunlit absorbed shortwave radiation [W m⁻²].
+        ASW_shaded: Shaded absorbed shortwave radiation [W m⁻²].
+        ASW_soil_Wm2: Absorbed shortwave radiation in soil [W m⁻²].
+        Vcmax25_sunlit: Sunlit maximum carboxylation rate at 25°C [μmol m⁻² s⁻¹].
+        Vcmax25_shaded: Shaded maximum carboxylation rate at 25°C [μmol m⁻² s⁻¹].
+        ball_berry_slope: Ball-Berry slope [-].
+        ball_berry_intercept: Ball-Berry intercept [-].
+        sunlit_fraction: Sunlit fraction of canopy [-].
+        G: Soil heat flux [W m⁻²].
+        SZA: Solar zenith angle [degrees].
+        Ca: Atmospheric CO2 concentration [μmol mol⁻¹].
+        Ps_Pa: Surface pressure [Pa].
+        gamma: Psychrometric constant [Pa K⁻¹].
+        Cp: Specific heat capacity of air [J kg⁻¹ K⁻¹].
+        rhoa: Air density [kg m⁻³].
+        VPD_Pa: Vapor pressure deficit [Pa].
+        RH: Relative humidity as a fraction [-].
+        desTa: 1st derivative of saturated vapor pressure [Pa K⁻¹].
+        ddesTa: 2nd derivative of saturated vapor pressure [Pa K⁻²].
+        epsa: Clear-sky emissivity [-].
+        Rc: Canopy resistance [s m⁻¹].
+        Rs: Soil resistance [s m⁻¹].
+        carbon_uptake_efficiency: Intrinsic quantum efficiency of carbon uptake [-].
+        fStress: Stress factor [-].
+        C4_photosynthesis: Whether to use C4 photosynthesis (True) or C3 (False).
+        passes: Number of iterations.
+
+    Returns:
+        GPP: Gross primary productivity [μmol m⁻² s⁻¹].
+        LE: Latent heat flux [W m⁻²].
+        LE_soil: Soil latent heat flux [W m⁻²].
+        LE_canopy: Canopy latent heat flux [W m⁻²].
+        Rn: Net radiation [W m⁻²].
+        Rn_soil: Soil net radiation [W m⁻²].
+        Rn_canopy: Canopy net radiation [W m⁻²].
+    """
+
+    # carbon = 4 if C4_photosynthesis else 3
+    GPP_max = 50 if C4_photosynthesis else 40
+
+    # this model originally initialized soil and canopy temperature to air temperature
+    Tf_sunlit_K = canopy_temperature_K
+    Tf_shaded_K = canopy_temperature_K
+    Tf_K = canopy_temperature_K
+    Ts_K = soil_temperature_K
+
+    # initialize intercellular CO2 concentration to atmospheric CO2 concentration depending on C3 or C4 photosynthesis
+    chi = 0.4 if C4_photosynthesis else 0.7
+    Ci_sunlit = Ca * chi
+    Ci_shaded = Ca * chi
+
+    ball_berry_intercept = ball_berry_intercept * fStress
+
+    epsf = 0.98
+    epss = 0.96
+
+    # initialize sunlit partition (overwritten when iterations process)
+
+    # initialize sunlit net assimilation rate to zero
+    net_assimilation_sunlit_μmolm2s1 = Tf_sunlit_K * 0
+
+    # initialize sunlit net radiation to zero
+    Rn_sunlit_Wm2 = Tf_sunlit_K * 0
+
+    # initialize sunlit latent heat flux to zero
+    LE_sunlit_Wm2 = Tf_sunlit_K * 0
+
+    # initialize sunlit sensible heat flux to zero
+    H_sunlit_Wm2 = Tf_sunlit_K * 0
+
+    # initialize shaded partition (overwritten when iterations process)
+
+    # initialize shaded net assimilation rate to zero
+    net_assimilation_shade_μmolm2s1 = Tf_shaded_K * 0
+
+    # initialize shaded net radiation to zero
+    Rn_shaded_Wm2 = Tf_shaded_K * 0
+
+    # initialize shaded latent heat flux to zero
+    LE_shaded_Wm2 = Tf_shaded_K * 0
+
+    # initialize shaded sensible heat flux to zero
+    H_shaded_Wm2 = Tf_shaded_K * 0
+
+    # initialize soil partition (overwritten when iterations process)
+
+    # initialize soil net radiation to zero
+    Rn_soil_Wm2 = Ts_K * 0
+
+    # initialize soil latent heat flux to zero
+    LE_soil_Wm2 = Ts_K * 0
+
+    # Iteration
+    for iter in range(1, passes + 1):
+
+        # Longwave radiation
+        # CLR:[ALW_Sun, ALW_shaded, ALW_Soil, Ls, La]
+        ALW_sunlit_Wm2, ALW_shaded_Wm2, ALW_soil_Wm2, Ls, La, Lf = canopy_longwave_radiation(
+            LAI=LAI,  # leaf area index (LAI) [-]
+            SZA=SZA_deg,  # solar zenith angle (degrees)
+            Ts_K=Ts_K,  # soil temperature (Ts) [K]
+            Tf_K=Tf_K,  # foliage temperature (Tf) [K]
+            Ta_K=Ta_K,  # air temperature (Ta) [K]
+            epsa=epsa,  # clear-sky emissivity (epsa) [-]
+            epsf=epsf,  # foliage emissivity (epsf) [-]
+            epss=epss  # soil emissivity (epss) [-],
+        )
+
+        # calculate sunlit photosynthesis
+        if C4_photosynthesis:
+            # calculate sunlit photosynthesis for C4 plants
+            photosynthesis_sunlit_C4_results = calculate_C4_photosynthesis(
+                Tf_K=Tf_sunlit_K,  # sunlit leaf temperature (Tf) [K]
+                Ci_μmol_per_mol=Ci_sunlit,  # sunlit intercellular CO2 concentration (Ci) [umol mol-1]
+                APAR_μmolm2s1=APAR_sunlit_μmolm2s1,  # sunlit leaf absorptance to photosynthetically active radiation [umol m-2 s-1]
+                Vcmax25_μmolm2s1=Vcmax25_sunlit  # sunlit maximum carboxylation rate at 25C (Vcmax25) [umol m-2 s-1]
+            )
+
+            net_assimilation_sunlit_μmolm2s1 = photosynthesis_sunlit_C4_results['net_assimilation_C4_μmolm2s1']
+        else:
+            # calculate sunlit photosynthesis for C3 plants
+            photosynthesis_sunlit_C3_results = calculate_C3_photosynthesis(
+                Tf_K=Tf_sunlit_K,  # sunlit leaf temperature (Tf) [K]
+                Ci=Ci_sunlit,  # sunlit intercellular CO2 concentration (Ci) [umol mol-1]
+                APAR_μmolm2s1=APAR_sunlit_μmolm2s1,  # sunlit leaf absorptance to photosynthetically active radiation [umol m-2 s-1]
+                Vcmax25=Vcmax25_sunlit,  # sunlit maximum carboxylation rate at 25C (Vcmax25) [umol m-2 s-1]
+                Ps_Pa=Ps_Pa,  # surface pressure (Ps) [Pa]
+                carbon_uptake_efficiency=carbon_uptake_efficiency  # intrinsic quantum efficiency for carbon uptake
+            )
+
+            net_assimilation_sunlit_μmolm2s1 = photosynthesis_sunlit_C3_results['net_assimilation_C3_μmolm2s1']
+
+        # calculate sunlit energy balance
+        Rn_sunlit_new_Wm2, LE_sunlit_new_Wm2, H_sunlit_new_Wm2, Tf_sunlit_new_K, gs2_sunlit_new, Ci_sunlit_new = canopy_energy_balance(
+            An=net_assimilation_sunlit_μmolm2s1,  # net assimulation (An) [umol m-2 s-1]
+            ASW_Wm2=ASW_sunlit_Wm2,  # total absorbed shortwave radiation by sunlit canopy (ASW) [W/m^2]
+            ALW_Wm2=ALW_sunlit_Wm2,  # total absorbed longwave radiation by sunlit canopy (ALW) [W/m^2]
+            Tf_K=Tf_sunlit_K,  # sunlit leaf temperature (Tf) [K]
+            Ps_Pa=Ps_Pa,  # surface pressure (Ps) [Pa]
+            Ca=Ca,  # ambient CO2 concentration (Ca) [umol mol-1]
+            Ta_K=Ta_K,  # air temperature (Ta) [K]
+            RH=RH,  # relative humidity (RH) [-]
+            VPD_Pa=VPD_Pa,  # water vapour deficit (VPD) [Pa]
+            desTa=desTa,  # 1st derivative of saturated vapour pressure (desTa)
+            ddesTa=ddesTa,  # 2nd derivative of saturated vapour pressure (ddesTa)
+            gamma=gamma,  # psychrometric constant (gamma) [pa K-1]
+            Cp=Cp,  # specific heat of air at constant pressure (Cp) [J kg-1 K-1]
+            rhoa=rhoa,  # air density (rhoa) [kg m-3]
+            Rc=Rc,  # TODO is this Ra or Rc in Ball-Berry?
+            ball_berry_slope=ball_berry_slope,  # Ball-Berry slope (m) [-]
+            ball_berry_intercept=ball_berry_intercept,  # Ball-Berry intercept (b0) [-]
+            C4_photosynthesis=C4_photosynthesis  # process for C4 plants instead of C3
+        )
+
+        # filter in sunlit energy balance estimates
+        Rn_sunlit_Wm2 = np.where(np.isnan(Rn_sunlit_new_Wm2), Rn_sunlit_Wm2, Rn_sunlit_new_Wm2)
+        LE_sunlit_Wm2 = np.where(np.isnan(LE_sunlit_new_Wm2), LE_sunlit_Wm2, LE_sunlit_new_Wm2)
+        H_sunlit_Wm2 = np.where(np.isnan(H_sunlit_new_Wm2), H_sunlit_Wm2, H_sunlit_new_Wm2)
+        Tf_sunlit_K = np.where(np.isnan(Tf_sunlit_new_K), Tf_sunlit_K, Tf_sunlit_new_K)
+        Ci_sunlit = np.where(np.isnan(Ci_sunlit_new), Ci_sunlit, Ci_sunlit_new)
+
+        # Photosynthesis (shade)
+        if C4_photosynthesis:
+            photosynthesis_shade_C4_results = calculate_C4_photosynthesis(
+                Tf_K=Tf_shaded_K,  # shaded leaf temperature (Tf) [K]
+                Ci_μmol_per_mol=Ci_shaded,  # shaded intercellular CO2 concentration (Ci) [umol mol-1]
+                APAR_μmolm2s1=APAR_shaded_μmolm2s1,  # shaded absorbed photosynthetically active radiation (APAR) [umol m-2 s-1]
+                Vcmax25_μmolm2s1=Vcmax25_shaded  # shaded maximum carboxylation rate at 25C (Vcmax25) [umol m-2 s-1]
+            )
+
+            net_assimilation_shade_μmolm2s1 = photosynthesis_shade_C4_results['net_assimilation_C4_μmolm2s1']
+        else:
+            photosynthesis_shade_C3_results = calculate_C3_photosynthesis(
+                Tf_K=Tf_shaded_K,  # shaded leaf temperature (Tf) [K]
+                Ci=Ci_shaded,  # shaed intercellular CO2 concentration (Ci) [umol mol-1]
+                APAR_μmolm2s1=APAR_shaded_μmolm2s1,  # shaded absorbed photosynthetically active radiation (APAR) [umol m-2 s-1]
+                Vcmax25=Vcmax25_shaded,  # shaded maximum carboxylation rate at 25C (Vcmax25) [umol m-2 s-1]
+                Ps_Pa=Ps_Pa,  # surface pressure (Ps) [Pa]
+                carbon_uptake_efficiency=carbon_uptake_efficiency  # intrinsic quantum efficiency for carbon uptake
+            )
+
+            net_assimilation_shade_μmolm2s1 = photosynthesis_shade_C3_results['net_assimilation_C3_μmolm2s1']
+
+        # calculated shaded energy balance
+        Rn_shaded_new, LE_shaded_new, H_shaded_new, Tf_K_shaded_new, gs2_shaded_new, Ci_shaded_new = canopy_energy_balance(
+            An=net_assimilation_shade_μmolm2s1,  # net assimulation (An) [umol m-2 s-1]
+            ASW_Wm2=ASW_shaded_Wm2,  # total absorbed shortwave radiation by shaded canopy (ASW) [umol m-2 s-1]
+            ALW_Wm2=ALW_shaded_Wm2,  # total absorbed longwave radiation by shaded canopy (ALW) [umol m-2 s-1]
+            Tf_K=Tf_shaded_K,  # shaded leaf temperature (Tf) [K]
+            Ps_Pa=Ps_Pa,  # surface pressure (Ps) [Pa]
+            Ca=Ca,  # ambient CO2 concentration (Ca) [umol mol-1]
+            Ta_K=Ta_K,  # air temperature (Ta) [K]
+            RH=RH,  # relative humidity as a fraction
+            VPD_Pa=VPD_Pa,  # water vapour deficit (VPD) [Pa]
+            desTa=desTa,  # 1st derivative of saturated vapour pressure (desTa)
+            ddesTa=ddesTa,  # 2nd derivative of saturated vapour pressure (ddesTa)
+            gamma=gamma,  # psychrometric constant (gamma) [pa K-1]
+            Cp=Cp,  # specific heat of air (Cp) [J kg-1 K-1]
+            rhoa=rhoa,  # air density (rhoa) [kg m-3]
+            Rc=Rc,
+            ball_berry_slope=ball_berry_slope,  # Ball-Berry slope (m) [-]
+            ball_berry_intercept=ball_berry_intercept,  # Ball-Berry intercept (b0) [-]
+            C4_photosynthesis=C4_photosynthesis  # process for C4 plants instead of C3
+        )
+
+        # filter in shaded energy balance estimates
+        Rn_shaded_Wm2 = np.where(np.isnan(Rn_shaded_new), Rn_shaded_Wm2, Rn_shaded_new)
+        LE_shaded_Wm2 = np.where(np.isnan(LE_shaded_new), LE_shaded_Wm2, LE_shaded_new)
+        H_shaded_Wm2 = np.where(np.isnan(H_shaded_new), H_shaded_Wm2, H_shaded_new)
+        Tf_shaded_K = np.where(np.isnan(Tf_K_shaded_new), Tf_shaded_K, Tf_K_shaded_new)
+        Ci_shaded = np.where(np.isnan(Ci_shaded_new), Ci_shaded, Ci_shaded_new)
+
+        # calculate soil energy balance
+        Rn_soil_new, LE_soil_new, Ts_K_soil_new = soil_energy_balance(
+            Ts_K=Ts_K,  # soil temperature in Kelvin
+            Ta_K=Ta_K,  # air temperature in Kelvin
+            G_Wm2=G_Wm2,  # soil heat flux (G) [W m-2]
+            VPD_Pa=VPD_Pa,  # water vapour deficit in Pascal
+            RH=RH,  # relative humidity as a fraction
+            gamma=gamma,  # psychrometric constant (gamma) [pa K-1]
+            Cp=Cp,  # specific heat of air (Cp) [J kg-1 K-1]
+            rhoa=rhoa,  # air density (rhoa) [kg m-3]
+            desTa=desTa,
+            Rs=Rs,
+            ASW_soil_Wm2=ASW_soil_Wm2,  # total absorbed shortwave radiation by soil (ASW) [umol m-2 s-1]
+            ALW_soil_Wm2=ALW_soil_Wm2,  # total absorbed longwave radiation by soil (ALW) [umol m-2 s-1]
+            Ls=Ls,
+            epsa=epsa
+        )
+
+        # filter in soil energy balance estimates
+        # where new estimates are missing, retain the prior estimates
+        Rn_soil_Wm2 = np.where(np.isnan(Rn_soil_new), Rn_soil_Wm2, Rn_soil_new)
+        LE_soil_Wm2 = np.where(np.isnan(LE_soil_new), LE_soil_Wm2, LE_soil_new)
+        Ts_K = np.where(np.isnan(Ts_K_soil_new), Ts_K, Ts_K_soil_new)
+
+        # combine sunlit and shaded foliage temperatures
+        Tf_K_new = (((Tf_sunlit_K ** 4) * sunlit_fraction + (Tf_shaded_K ** 4) * (1 - sunlit_fraction)) ** 0.25)
+        Tf_K = np.where(np.isnan(Tf_K_new), Tf_K, Tf_K_new)
+
+    # calculate canopy latent heat flux
+    LE_canopy_Wm2 = np.clip(LE_sunlit_Wm2 + LE_shaded_Wm2, 0, 1000)
+
+    # calculate latent heat flux
+    LE_Wm2 = np.clip(LE_sunlit_Wm2 + LE_shaded_Wm2 + LE_soil_Wm2, 0, 1000)  # [W m-2]
+
+    # calculate gross primary productivity
+    GPP = np.clip(net_assimilation_sunlit_μmolm2s1 + net_assimilation_shade_μmolm2s1, 0, GPP_max)  # [umol m-2 s-1]
+
+    # calculate canopy net radiation
+    Rn_canopy_Wm2 = np.clip(Rn_sunlit_Wm2 + Rn_shaded_Wm2, 0, None)
+
+    # calculate net radiation
+    Rn_Wm2 = np.clip(Rn_sunlit_Wm2 + Rn_shaded_Wm2 + Rn_soil_Wm2, 0, 1000)  # [W m-2]
+
+    return GPP, LE_Wm2, LE_soil_Wm2, LE_canopy_Wm2, Rn_Wm2, Rn_soil_Wm2, Rn_canopy_Wm2

BESS_JPL/colors.py

@@ -0,0 +1,33 @@
+from matplotlib.colors import LinearSegmentedColormap
+
+GPP_COLORMAP = LinearSegmentedColormap.from_list(
+    name="GPP",
+    colors=[
+        "#000000",
+        "#bdae08",
+        "#325e32",
+        "#a6ff01",
+        "#00ff00"
+    ]
+)
+
+ET_COLORMAP = LinearSegmentedColormap.from_list("ET", [
+    "#f6e8c3",
+    "#d8b365",
+    "#99974a",
+    "#53792d",
+    "#6bdfd2",
+    "#1839c5"
+])
+
+NDVI_COLORMAP_ABSOLUTE = LinearSegmentedColormap.from_list(
+    name="NDVI",
+    colors=[
+        (0, "#0000ff"),
+        (0.4, "#000000"),
+        (0.5, "#745d1a"),
+        (0.6, "#e1dea2"),
+        (0.8, "#45ff01"),
+        (1, "#325e32")
+    ]
+)

BESS_JPL/constants.py

@@ -0,0 +1,25 @@
+A = 0.3
+KPAR = 0.5
+MIN_FIPAR = 0.0
+MAX_FIPAR = 1.0
+MIN_LAI = 0.0
+MAX_LAI = 10.0
+BALL_BERRY_INTERCEPT_C4 = 0.04
+RESAMPLING = "cubic"
+
+# Default scale factor for C4 fraction
+C4_FRACTION_SCALE_FACTOR = 0.01
+
+UPSCALE_TO_DAYLIGHT = True
+
+# GEOS-5 FP variables retrieved by the model
+GEOS5FP_INPUTS = [
+    "Ta_C",        # Air temperature (°C)
+    "RH",          # Relative humidity (fraction)
+    "COT",         # Cloud optical thickness
+    "AOT",         # Aerosol optical thickness
+    "PAR_albedo",    # Visible direct beam albedo
+    "NIR_albedo",    # Near-infrared direct beam albedo
+    "Ca",       # Atmospheric CO₂ concentration (ppm)
+    "wind_speed_mps"   # Wind speed (m/s)
+]

BESS_JPL/exceptions.py

@@ -0,0 +1,3 @@
+class MissingOfflineParameter(Exception):
+    """Exception raised when a required parameter is missing in offline mode."""
+    pass

BESS_JPL/generate_BESS_GEOS5FP_inputs.py

@@ -0,0 +1,58 @@
+from os.path import dirname, join
+import logging
+import sys
+
+# Allow running as script while preserving package imports
+if __name__ == "__main__" and __package__ is None:
+    sys.path.insert(0, dirname(dirname(__file__)))
+    __package__ = "BESS_JPL"
+
+from ECOv002_calval_tables import load_times_locations, load_calval_table
+from GEOS5FP import GEOS5FP
+from BESS_JPL import GEOS5FP_INPUTS
+
+logger = logging.getLogger(__name__)
+
+def generate_BESS_GEOS5FP_inputs(
+        filename: str = None,
+        update_package_data: bool = True,
+        sample_size: int = None) -> None:
+    logger.info("Generating BESS-JPL GEOS-5 FP input table:")
+
+    for item in GEOS5FP_INPUTS:
+        logger.info(f"  - {item}")
+
+    # Load sample times and locations
+    targets_df = load_times_locations()
+    calval_table_df = load_calval_table()
+    
+    if sample_size is not None:
+        targets_df = targets_df.sample(n=sample_size).reset_index(drop=True)
+
+    # Create GEOS5FP connection
+    GEOS5FP_connection = GEOS5FP()
+    
+    target_variables = [
+        variable
+        for variable
+        in GEOS5FP_INPUTS
+        if variable not in calval_table_df.columns
+    ]
+
+    # Query for FLiESANN GEOS5FP input variables
+    results_df = GEOS5FP_connection.query(
+        target_variables=target_variables,
+        targets_df=targets_df
+    )
+
+    if update_package_data and not sample_size:
+        if filename is None:
+            filename = join(dirname(__file__), "ECOv002-cal-val-BESS-JPL-GEOS5FP-inputs.csv")
+
+        results_df.to_csv(filename, index=False)
+
+    return results_df
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    generate_BESS_GEOS5FP_inputs()

BESS_JPL/generate_BESS_inputs_table.py

@@ -0,0 +1,186 @@
+import logging
+
+import numpy as np
+import pandas as pd
+import rasters as rt
+from dateutil import parser
+from pandas import DataFrame
+from rasters import MultiPoint, WGS84
+from shapely.geometry import Point
+from GEOS5FP import GEOS5FP
+from MODISCI import MODISCI
+from NASADEM import NASADEMConnection
+from gedi_canopy_height import GEDI_DOWNLOAD_DIRECTORY
+from .retrieve_BESS_inputs import retrieve_BESS_inputs
+from .constants import C4_FRACTION_SCALE_FACTOR, RESAMPLING
+
+logger = logging.getLogger(__name__)
+
+def generate_BESS_inputs_table(
+        input_df: DataFrame,
+        GEOS5FP_connection: GEOS5FP = None,
+        MODISCI_connection: MODISCI = None,
+        NASADEM_connection: NASADEMConnection = None,
+        C4_fraction_scale_factor: float = C4_FRACTION_SCALE_FACTOR,
+        resampling: str = RESAMPLING,
+        GEDI_download_directory: str = GEDI_DOWNLOAD_DIRECTORY) -> DataFrame:
+    """
+    Generates a DataFrame of BESS-JPL inputs by retrieving atmospheric, vegetation, and static data.
+    
+    This is a simple wrapper around retrieve_BESS_inputs that handles DataFrame
+    input/output and geometry parsing.
+
+    Parameters:
+    input_df (pd.DataFrame): A DataFrame containing the following columns:
+        - time_UTC (str or datetime): Time in UTC.
+        - geometry (str or shapely.geometry.Point) or (lat, lon): Spatial coordinates. 
+          If "geometry" is a string, it should be in WKT format (e.g., "POINT (lon lat)").
+        - ST_C (float): Surface temperature in Celsius.
+        - NDVI (float): Normalized Difference Vegetation Index.
+        - albedo (float): Surface albedo.
+        - Ta_C (float, optional): Air temperature in Celsius.
+        - RH (float, optional): Relative humidity as a proportion.
+        - elevation_m (float, optional): Elevation in meters.
+        - NDVI_minimum (float, optional): Minimum NDVI.
+        - NDVI_maximum (float, optional): Maximum NDVI.
+        - COT (float, optional): Cloud optical thickness.
+        - AOT (float, optional): Aerosol optical thickness.
+        - vapor_gccm (float, optional): Water vapor in grams per cubic centimeter.
+        - ozone_cm (float, optional): Ozone concentration in centimeters.
+        - KG or KG_climate (str, optional): Köppen-Geiger climate classification.
+        - canopy_height_meters (float, optional): Canopy height in meters.
+        - Ca (float, optional): Atmospheric CO2 concentration in ppm.
+        - wind_speed_mps (float, optional): Wind speed in meters per second.
+        - SZA_deg (float, optional): Solar zenith angle in degrees.
+        - canopy_temperature_C (float, optional): Canopy temperature in Celsius.
+        - soil_temperature_C (float, optional): Soil temperature in Celsius.
+        - C4_fraction (float, optional): Fraction of C4 plants.
+        - carbon_uptake_efficiency (float, optional): Intrinsic quantum efficiency for carbon uptake.
+        - kn (float, optional): Nitrogen decay coefficient.
+        - ball_berry_intercept_C3 (float, optional): Ball-Berry intercept for C3 plants.
+        - ball_berry_slope_C3 (float, optional): Ball-Berry slope for C3 plants.
+        - ball_berry_slope_C4 (float, optional): Ball-Berry slope for C4 plants.
+        - peakVCmax_C3_μmolm2s1 (float, optional): Peak maximum carboxylation rate for C3 plants.
+        - peakVCmax_C4_μmolm2s1 (float, optional): Peak maximum carboxylation rate for C4 plants.
+        - CI (float, optional): Clumping index.
+        - PAR_albedo (float, optional): Surface albedo in visible wavelengths.
+        - NIR_albedo (float, optional): Surface albedo in near-infrared wavelengths.
+        - day_of_year (float, optional): Day of year.
+        - hour_of_day (float, optional): Hour of day.
+    GEOS5FP_connection (GEOS5FP, optional): Connection object for GEOS-5 FP data.
+    MODISCI_connection (MODISCI, optional): Connection object for MODIS clumping index data.
+    NASADEM_connection (NASADEMConnection, optional): Connection object for NASADEM data.
+    C4_fraction_scale_factor (float, optional): Scale factor for C4 fraction adjustment.
+    resampling (str, optional): Resampling method for data processing.
+    GEDI_download_directory (str, optional): Directory for GEDI canopy height data downloads.
+
+    Returns:
+    pd.DataFrame: A DataFrame with the same structure as the input, but with additional columns
+        containing all BESS-JPL input variables that were retrieved or calculated.
+
+    Raises:
+    KeyError: If required columns ("geometry" or "lat" and "lon", "time_UTC", "ST_C", "NDVI", "albedo") are missing.
+    """
+    def ensure_geometry(row):
+        if "geometry" in row:
+            if isinstance(row.geometry, str):
+                s = row.geometry.strip()
+                if s.startswith("POINT"):
+                    coords = s.replace("POINT", "").replace("(", "").replace(")", "").strip().split()
+                    return Point(float(coords[0]), float(coords[1]))
+                elif "," in s:
+                    coords = [float(c) for c in s.split(",")]
+                    return Point(coords[0], coords[1])
+                else:
+                    coords = [float(c) for c in s.split()]
+                    return Point(coords[0], coords[1])
+        return row.geometry
+
+    logger.info("started generating BESS inputs table")
+
+    # Ensure geometry column is properly formatted
+    input_df = input_df.copy()
+    input_df["geometry"] = input_df.apply(ensure_geometry, axis=1)
+
+    # Prepare output DataFrame
+    output_df = input_df.copy()
+    
+    # Prepare geometries
+    if "geometry" in input_df.columns:
+        geometries = MultiPoint([(geom.x, geom.y) for geom in input_df.geometry], crs=WGS84)
+    elif "lat" in input_df.columns and "lon" in input_df.columns:
+        geometries = MultiPoint([(lon, lat) for lon, lat in zip(input_df.lon, input_df.lat)], crs=WGS84)
+    else:
+        raise KeyError("Input DataFrame must contain either 'geometry' or both 'lat' and 'lon' columns.")
+    
+    # Convert time column to datetime
+    times_UTC = pd.to_datetime(input_df.time_UTC)
+    
+    logger.info(f"generating inputs for {len(input_df)} rows")
+
+    # Helper function to get column values or None if column doesn't exist
+    def get_column_or_none(df, col_name, default_col_name=None):
+        if col_name in df.columns:
+            return df[col_name].values
+        elif default_col_name and default_col_name in df.columns:
+            return df[default_col_name].values
+        else:
+            return None
+
+    # Retrieve all inputs at once using vectorized retrieve_BESS_inputs call
+    BESS_inputs = retrieve_BESS_inputs(
+        ST_C=get_column_or_none(input_df, "ST_C"),
+        NDVI=get_column_or_none(input_df, "NDVI"),
+        albedo=get_column_or_none(input_df, "albedo"),
+        geometry=geometries,
+        time_UTC=times_UTC,
+        hour_of_day=get_column_or_none(input_df, "hour_of_day"),
+        day_of_year=get_column_or_none(input_df, "day_of_year"),
+        GEOS5FP_connection=GEOS5FP_connection,
+        elevation_m=get_column_or_none(input_df, "elevation_m"),
+        Ta_C=get_column_or_none(input_df, "Ta_C"),
+        RH=get_column_or_none(input_df, "RH"),
+        NDVI_minimum=get_column_or_none(input_df, "NDVI_minimum"),
+        NDVI_maximum=get_column_or_none(input_df, "NDVI_maximum"),
+        PAR_albedo=get_column_or_none(input_df, "PAR_albedo"),
+        NIR_albedo=get_column_or_none(input_df, "NIR_albedo"),
+        COT=get_column_or_none(input_df, "COT"),
+        AOT=get_column_or_none(input_df, "AOT"),
+        vapor_gccm=get_column_or_none(input_df, "vapor_gccm"),
+        ozone_cm=get_column_or_none(input_df, "ozone_cm"),
+        KG_climate=get_column_or_none(input_df, "KG_climate", "KG"),
+        canopy_height_meters=get_column_or_none(input_df, "canopy_height_meters"),
+        Ca=get_column_or_none(input_df, "Ca"),
+        wind_speed_mps=get_column_or_none(input_df, "wind_speed_mps"),
+        SZA_deg=get_column_or_none(input_df, "SZA_deg", "SZA"),
+        canopy_temperature_C=get_column_or_none(input_df, "canopy_temperature_C"),
+        soil_temperature_C=get_column_or_none(input_df, "soil_temperature_C"),
+        C4_fraction=get_column_or_none(input_df, "C4_fraction"),
+        carbon_uptake_efficiency=get_column_or_none(input_df, "carbon_uptake_efficiency"),
+        kn=get_column_or_none(input_df, "kn"),
+        ball_berry_intercept_C3=get_column_or_none(input_df, "ball_berry_intercept_C3"),
+        ball_berry_slope_C3=get_column_or_none(input_df, "ball_berry_slope_C3"),
+        ball_berry_slope_C4=get_column_or_none(input_df, "ball_berry_slope_C4"),
+        peakVCmax_C3_μmolm2s1=get_column_or_none(input_df, "peakVCmax_C3_μmolm2s1", "peakVCmax_C3"),
+        peakVCmax_C4_μmolm2s1=get_column_or_none(input_df, "peakVCmax_C4_μmolm2s1", "peakVCmax_C4"),
+        CI=get_column_or_none(input_df, "CI"),
+        C4_fraction_scale_factor=C4_fraction_scale_factor,
+        MODISCI_connection=MODISCI_connection,
+        NASADEM_connection=NASADEM_connection,
+        resampling=resampling,
+        GEDI_download_directory=GEDI_download_directory
+    )
+
+    # Add retrieved inputs to the output DataFrame
+    for key, values in BESS_inputs.items():
+        # Skip values with mismatched lengths
+        if hasattr(values, '__len__') and not isinstance(values, str):
+            if len(values) != len(output_df):
+                logger.warning(f"Skipping {key}: length mismatch ({len(values)} != {len(output_df)})")
+                continue
+        logger.info(f"Adding {key} to output DataFrame (type: {type(values)}, length: {len(values) if hasattr(values, '__len__') and not isinstance(values, str) else 'N/A'})")
+        output_df[key] = values
+
+    logger.info("completed generating BESS inputs table")
+
+    return output_df