BESS-JPL 1.26.1__tar.gz

bess_jpl-1.26.1/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3  # This is already the latest version
+
+      - name: Set up Python
+        uses: actions/setup-python@v4  # This is also the latest version
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]  # Use dev to install pytest
+
+      - name: Run tests
+        run: |
+          pytest

bess_jpl-1.26.1/.github/workflows/python-publish.yml

@@ -0,0 +1,39 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

bess_jpl-1.26.1/BESS_JPL/BESS_JPL.py

@@ -0,0 +1,54 @@
+from typing import Union
+from datetime import datetime
+import logging
+import numpy as np
+
+import rasters as rt
+from rasters import Raster, RasterGeometry
+
+from check_distribution import check_distribution
+
+from sun_angles import calculate_SZA_from_DOY_and_hour
+from solar_apparent_time import solar_day_of_year_for_area, solar_hour_of_day_for_area
+
+from koppengeiger import load_koppen_geiger
+from gedi_canopy_height import load_canopy_height
+from FLiESANN import FLiESANN
+from GEOS5FP import GEOS5FP
+from MODISCI import MODISCI
+from NASADEM import NASADEM
+
+from .constants import *
+from .C3_photosynthesis import *
+from .C4_photosynthesis import *
+from .canopy_energy_balance import *
+from .canopy_longwave_radiation import *
+from .canopy_shortwave_radiation import *
+from .carbon_water_fluxes import *
+from .FVC_from_NDVI import *
+from .interpolate_C3_C4 import *
+from .LAI_from_NDVI import *
+from .load_C4_fraction import *
+from .load_carbon_uptake_efficiency import *
+from .load_kn import *
+from .load_NDVI_minimum import *
+from .load_NDVI_maximum import *
+from .load_peakVCmax_C3 import *
+from .load_peakVCmax_C4 import *
+from .load_ball_berry_intercept_C3 import *
+from .load_ball_berry_slope_C3 import *
+from .load_ball_berry_slope_C4 import *
+from .calculate_VCmax import *
+from .meteorology import *
+from .soil_energy_balance import *
+from .model import *
+from .process_BESS_table import *
+from .generate_BESS_inputs_table import *
+from .ECOv002_static_tower_BESS_inputs import *
+from .ECOv002_calval_BESS_inputs import *
+from .verify import *
+from .colors import *
+from .generate_input_dataset import *
+from .generate_BESS_inputs_table import *
+from .generate_output_dataset import *
+from .exceptions import *

bess_jpl-1.26.1/BESS_JPL/C3_photosynthesis.py

@@ -0,0 +1,165 @@
+import numpy as np
+
+
+def calculate_C3_photosynthesis(
+        Tf_K: np.ndarray,  # leaf temperature in Kelvin (K)
+        Ci: np.ndarray,  # intercellular CO2 concentration in micromoles per mole (μmol mol⁻¹)
+        APAR_μmolm2s1: np.ndarray,  # absorbed photosynthetically active radiation in micromoles per square meter per second (μmol m⁻² s⁻¹)
+        Vcmax25: np.ndarray,  # maximum carboxylation rate at 25°C in micromoles per square meter per second (μmol m⁻² s⁻¹)
+        Ps_Pa: np.ndarray,  # surface pressure in Pascals (Pa)
+        carbon_uptake_efficiency: np.ndarray) -> dict:  # intrinsic quantum efficiency for carbon uptake (unitless)
+    """
+    photosynthesis for C3 plants
+    Collatz et al., 1991
+    https://www.sciencedirect.com/science/article/abs/pii/0168192391900028
+    Adapted from Youngryel Ryu's code by Gregory Halverson and Robert Freepartner
+    :param Tf_K: leaf temperature in Kelvin
+    :param Ci: intercellular CO2 concentration [umol mol-1]
+    :param APAR: leaf absorptance to photosynthetically active radiation [umol m-2 s-1]
+    :param Vcmax25: maximum carboxylation rate at 25C [umol m-2 s-1]
+    :param Ps_Pa: surface pressure in Pascal
+    :param carbon_uptake_efficiency: intrinsic quantum efficiency for carbon uptake
+    :return: dictionary containing photosynthesis, respiration, and net assimilation rates
+    """
+
+    # Universal gas constant used in temperature corrections
+    # Units: kilojoules per Kelvin per mole (kJ K⁻¹ mol⁻¹)
+    R = 8.314e-3
+
+    # Calculate oxygen concentration, assuming oxygen is 21% of the atmospheric pressure
+    # Units: Pascals (Pa)
+    O2 = Ps_Pa * 0.21
+
+    # Convert intercellular CO2 concentration to partial pressure in Pascal
+    # Units: Pascals (Pa)
+    Pi = Ci * 1e-6 * Ps_Pa
+
+    # Calculate temperature difference from 25°C (298.15 K), scaled by 10 for Q10 calculations
+    # Unitless
+    item = (Tf_K - 298.15) / 10
+
+    # Michaelis-Menten constant for CO2 at 25°C
+    # Units: Pascals (Pa)
+    KC25 = 30
+
+    # Michaelis-Menten constant for O2 at 25°C
+    # Units: Pascals (Pa)
+    KO25 = 30000
+
+    # Specificity factor of RuBisCO at 25°C
+    # Units: Pascals (Pa)
+    tao25 = 2600
+
+    # Q10 value for temperature sensitivity of KC
+    # Unitless
+    KCQ10 = 2.1
+
+    # Q10 value for temperature sensitivity of KO
+    # Unitless
+    KOQ10 = 1.2
+
+    # Q10 value for temperature sensitivity of tao
+    # Unitless
+    taoQ10 = 0.57
+
+    # Adjusted Michaelis-Menten constant for CO2 at the given temperature
+    # Units: Pascals (Pa)
+    KC = KC25 * KCQ10 ** item
+
+    # Adjusted Michaelis-Menten constant for O2 at the given temperature
+    # Units: Pascals (Pa)
+    KO = KO25 * KOQ10 ** item
+
+    # Effective Michaelis-Menten constant for CO2 considering O2 competition
+    # Units: Pascals (Pa)
+    K = KC * (1.0 + O2 / KO)
+
+    # Adjusted specificity factor of RuBisCO at the given temperature
+    # Units: Pascals (Pa)
+    tao = tao25 * taoQ10 ** item
+
+    # CO2 compensation point in the absence of dark respiration
+    # Units: Pascals (Pa)
+    GammaS = O2 / (2.0 * tao)
+
+    # Q10 value for temperature sensitivity of Vcmax
+    # Unitless
+    VcmaxQ10 = 2.4
+
+    # Adjusted Vcmax at the given temperature without activation energy correction
+    # Units: micromoles per square meter per second (μmol m⁻² s⁻¹)
+    Vcmax_o = Vcmax25 * VcmaxQ10 ** item
+
+    # Adjusted Vcmax at the given temperature with activation energy correction
+    # Units: micromoles per square meter per second (μmol m⁻² s⁻¹)
+    Vcmax = Vcmax_o / (1.0 + np.exp((-220.0 + 0.703 * Tf_K) / (R * Tf_K)))
+
+    # Base dark respiration rate as a fraction of Vcmax
+    # Units: micromoles per square meter per second (μmol m⁻² s⁻¹)
+    Rd_o = 0.015 * Vcmax
+
+    # Adjusted dark respiration rate at the given temperature
+    # Units: micromoles per square meter per second (μmol m⁻² s⁻¹)
+    respiration_C3_μmolm2s1 = Rd_o * 1.0 / (1.0 + np.exp(1.3 * (Tf_K - 273.15 - 55.0)))
+
+    # Rubisco-limited rate, dependent on CO2 availability and RuBisCO activity
+    # Units: micromoles per square meter per second (μmol m⁻² s⁻¹)
+    JC = Vcmax * (Pi - GammaS) / (Pi + K)
+
+    # Light-limited rate, dependent on light energy and CO2 availability
+    # Units: micromoles per square meter per second (μmol m⁻² s⁻¹)
+    JE = carbon_uptake_efficiency * APAR_μmolm2s1 * (Pi - GammaS) / (Pi + 2.0 * GammaS)
+
+    # Export-limited rate, dependent on the capacity to export photosynthetic products
+    # Units: micromoles per square meter per second (μmol m⁻² s⁻¹)
+    JS = Vcmax / 2.0
+
+    # Empirical colimitation factor for Rubisco-light limitation
+    # Unitless
+    a = 0.98
+
+    # Quadratic coefficient for colimitation (Rubisco-light limitation)
+    # Unitless
+    b = -(JC + JE)
+
+    # Quadratic coefficient for colimitation (Rubisco-light limitation)
+    # Unitless
+    c = JC * JE
+
+    # Combined Rubisco-light limitation
+    # Units: micromoles per square meter per second (μmol m⁻² s⁻¹)
+    JCE = (-b + np.sign(b) * np.sqrt(b * b - 4.0 * a * c)) / (2.0 * a)
+
+    # Ensure the result is real-valued for Rubisco-light limitation
+    # Units: micromoles per square meter per second (μmol m⁻² s⁻¹)
+    JCE = np.real(JCE)
+
+    # Empirical colimitation factor for Rubisco-light-export limitation
+    # Unitless
+    a = 0.95
+
+    # Quadratic coefficient for colimitation (Rubisco-light-export limitation)
+    # Unitless
+    b = -(JCE + JS)
+
+    # Quadratic coefficient for colimitation (Rubisco-light-export limitation)
+    # Unitless
+    c = JCE * JS
+
+    # Combined Rubisco-light-export limitation
+    # Units: micromoles per square meter per second (μmol m⁻² s⁻¹)
+    photosynthesis_C3_μmolm2s1 = (-b + np.sign(b) * np.sqrt(b * b - 4.0 * a * c)) / (2.0 * a)
+
+    # Ensure the result is real-valued for Rubisco-light-export limitation
+    # Units: micromoles per square meter per second (μmol m⁻² s⁻¹)
+    photosynthesis_C3_μmolm2s1 = np.real(photosynthesis_C3_μmolm2s1)
+
+    # Net assimilation rate, ensuring non-negative values
+    # Units: micromoles per square meter per second (μmol m⁻² s⁻¹)
+    net_assimilation_C3_μmolm2s1 = np.clip(photosynthesis_C3_μmolm2s1 - respiration_C3_μmolm2s1, 0, None)
+
+    return {
+        "photosynthesis_C3_μmolm2s1": photosynthesis_C3_μmolm2s1,
+        "respiration_C3_μmolm2s1": respiration_C3_μmolm2s1,
+        "net_assimilation_C3_μmolm2s1": net_assimilation_C3_μmolm2s1
+    }

bess_jpl-1.26.1/BESS_JPL/C4_fraction.tif.aux.xml

@@ -0,0 +1,11 @@
+<PAMDataset>
+  <PAMRasterBand band="1">
+    <Metadata>
+      <MDI key="STATISTICS_MAXIMUM">100</MDI>
+      <MDI key="STATISTICS_MEAN">3.2450253068732</MDI>
+      <MDI key="STATISTICS_MINIMUM">0</MDI>
+      <MDI key="STATISTICS_STDDEV">15.002005519213</MDI>
+      <MDI key="STATISTICS_VALID_PERCENT">100</MDI>
+    </Metadata>
+  </PAMRasterBand>
+</PAMDataset>

bess_jpl-1.26.1/BESS_JPL/C4_photosynthesis.py

@@ -0,0 +1,133 @@
+import numpy as np
+
+
+def calculate_C4_photosynthesis(
+        Tf_K: np.ndarray, 
+        Ci_μmol_per_mol: np.ndarray, 
+        APAR_μmolm2s1: np.ndarray, 
+        Vcmax25_μmolm2s1: np.ndarray) -> dict:
+    """
+    =============================================================================
+    Collatz et al., 1992
+
+    Module     : Photosynthesis for C4 plant
+    Description: This function calculates the net assimilation rate (An) for C4 plants
+                 based on the biochemical model described by Collatz et al. (1992).
+                 The model accounts for temperature corrections, light absorption,
+                 and CO2 availability to simulate photosynthetic rates under varying
+                 environmental conditions.
+
+    Parameters:
+        Tf_K (np.ndarray): Leaf temperature (Tf) in Kelvin. Temperature influences 
+                           enzyme kinetics and the rates of photosynthetic reactions.
+        Ci_μmol_per_mol (np.ndarray): Intercellular CO2 concentration (Ci) in 
+                                      micromoles per mole. Represents the CO2 available for fixation.
+        APAR_μmolm2s1 (np.ndarray): Absorbed photosynthetically active radiation (APAR) 
+                                     in micromoles per square meter per second. This is the light energy available for photosynthesis.
+        Vcmax25_μmolm2s1 (np.ndarray): Maximum carboxylation rate at 25°C (Vcmax25) in 
+                                       micromoles per square meter per second. Reflects the activity of the enzyme Rubisco.
+
+    Returns:
+        dict: A dictionary containing the following keys:
+            - 'net_assimilation_C4_μmolm2s1' (np.ndarray): Net assimilation rate (An) in micromoles per square meter per second.
+            - 'photosynthesis_C4_μmolm2s1' (np.ndarray): Photosynthesis rate in micromoles per square meter per second.
+            - 'respiration_C4_μmolm2s1' (np.ndarray): Respiration rate in micromoles per square meter per second.
+
+    Explanation:
+        The net assimilation rate (An) is the balance between the carbon dioxide fixed 
+        during photosynthesis and the carbon dioxide released during respiration. It 
+        quantifies the net carbon gain by the plant under given environmental conditions. 
+        This function models the biochemical processes that limit photosynthesis, 
+        including light availability, CO2 concentration, and enzyme activity, while 
+        accounting for temperature-dependent effects on these processes.
+
+    References:
+        Collatz, G. J., Ball, J. T., Grivet, C., & Berry, J. A. (1992). Physiological
+        and environmental regulation of stomatal conductance, photosynthesis, and
+        transpiration: A model that includes a laminar boundary layer. Agricultural
+        and Forest Meteorology, 54(2-4), 107-136.
+
+        DePury, D. G. G., & Farquhar, G. D. (1997). Simple scaling of photosynthesis
+        from leaves to canopies without the errors of big-leaf models. Plant, Cell &
+        Environment, 20(5), 537-557.
+    =============================================================================
+    """
+    # Calculate the temperature deviation from 25°C (298.15 K)
+    # `temperature_deviation` represents the temperature difference normalized to 10°C intervals
+    temperature_deviation = (Tf_K - 298.15) / 10.0
+
+    # Define the Q10 coefficient, which describes the rate increase for every 10°C rise
+    # A Q10 of 2.0 means the reaction rate doubles for every 10°C increase in temperature
+    Q10 = 2.0
+
+    # Calculate the temperature-dependent rate constant for CO2 fixation
+    # `k` is the rate constant for CO2 fixation, adjusted for temperature
+    k = 0.7 * pow(Q10, temperature_deviation)  # [mol m-2 s-1]
+
+    # Calculate the temperature-corrected maximum carboxylation rate
+    # `Vcmax_o` is the base maximum carboxylation rate adjusted for temperature
+    Vcmax_o = Vcmax25_μmolm2s1 * pow(Q10, temperature_deviation)  # [umol m-2 s-1]
+
+    # Further adjust `Vcmax_o` for enzyme deactivation at extreme temperatures
+    # `Vcmax` is the effective maximum carboxylation rate after accounting for temperature sensitivity
+    Vcmax = Vcmax_o / (
+        (1.0 + np.exp(0.3 * (286.15 - Tf_K))) * (1.0 + np.exp(0.3 * (Tf_K - 309.15)))
+    )  # [umol m-2 s-1]
+
+    # Calculate the temperature-corrected dark respiration rate
+    # `Rd_o` is the base dark respiration rate adjusted for temperature
+    Rd_o_μmolm2s1 = 0.8 * pow(Q10, temperature_deviation)  # [umol m-2 s-1]
+
+    # `Rd` is the effective dark respiration rate after accounting for temperature sensitivity
+    respiration_C4_μmolm2s1 = Rd_o_μmolm2s1 / (1.0 + np.exp(1.3 * (Tf_K - 328.15)))  # [umol m-2 s-1]
+
+    # Define the three limiting states of photosynthesis
+    # `Je` is the electron transport-limited rate, assumed to equal `Vcmax`
+    Je = Vcmax  # [umol m-2 s-1]
+
+    # Calculate the light-limited rate
+    # `quantum_yield` is the quantum yield (mol CO2 fixed per mol photons absorbed)
+    quantum_yield = 0.067  # Quantum yield
+
+    # `Ji` is the light-limited rate, determined by absorbed light energy
+    Ji_μmolm2s1 = quantum_yield * APAR_μmolm2s1  # [umol m-2 s-1]
+
+    # Calculate the CO2-limited rate
+    # `ci` is the intercellular CO2 concentration converted to mol/mol
+    ci = Ci_μmol_per_mol * 1e-6  # Convert [umol mol-1] to [mol mol-1]
+
+    # `Jc` is the CO2-limited rate, based on `ci` and the rate constant `k`
+    Jc = ci * k * 1e6  # [umol m-2 s-1]
+
+    # Colimitation between the three limiting states of photosynthesis
+    # Step 1: Colimitation between `Je` and `Ji`
+    # `a`, `b`, and `c` are coefficients for the quadratic equation
+    a = 0.83  # Empirical coefficient for colimitation
+    b = -(Je + Ji_μmolm2s1)
+    c = Je * Ji_μmolm2s1
+
+    # `Jei` is the intermediate colimited rate between `Je` and `Ji`
+    Jei = (-b + np.sign(b) * np.sqrt(b * b - 4.0 * a * c)) / (2.0 * a)
+    Jei = np.real(Jei)  # Ensure real values
+
+    # Step 2: Colimitation between `Jei` and `Jc`
+    # Update coefficients for the quadratic equation
+    a = 0.93  # Empirical coefficient for colimitation
+    b = -(Jei + Jc)
+    c = Jei * Jc
+
+    # `Jeic` is the final colimited rate between `Jei` and `Jc`
+    photosynthesis_C4_μmolm2s1 = (-b + np.sign(b) * np.sqrt(b * b - 4.0 * a * c)) / (2.0 * a)
+    photosynthesis_C4_μmolm2s1 = np.real(photosynthesis_C4_μmolm2s1)  # Ensure real values
+
+    # Calculate the net assimilation rate
+    # `An` is the net assimilation rate, clipped to ensure non-negative values
+    # It represents the net carbon gain by the plant, accounting for photosynthesis and respiration
+    net_assimilation_C4_μmolm2s1 = np.clip(photosynthesis_C4_μmolm2s1 - respiration_C4_μmolm2s1, 0, None)  # [umol m-2 s-1]
+
+    # Return results as a dictionary
+    return {
+        'net_assimilation_C4_μmolm2s1': net_assimilation_C4_μmolm2s1,
+        'photosynthesis_C4_μmolm2s1': photosynthesis_C4_μmolm2s1,
+        'respiration_C4_μmolm2s1': respiration_C4_μmolm2s1
+    }