scopeinpython.ebal

The SCOPE energy-balance closure loop: iterates sunlit/shaded leaf and soil temperature until sensible+latent heat flux matches net radiation, coupling radiative transfer, aerodynamics, photosynthesis/fluorescence and heat-flux partitioning. Direct, “SCOPE-lite”-only port of SCOPEinR::get.ebal – the top of the whole thermal energy-balance chain built this session.

Note

Depends on scopeinpython.rtmo.net_radiation_lite() and scopeinpython.rtmt_sb.rtmt_sb().

Only the default (non-MD12) fluorescence-model branch, only the simple G = 0.35*Rn ground-heat-flux method, and only meanleaf.v2’s 'layers' aggregation mode are ported (matches every reference case built during this whole port – see the module docstring for the full reasoning).

A subtlety not present in R’s own (fully vectorized) implementation: this Python port calls scopeinpython.biochemical.get_biochemical() once per canopy layer with scalar inputs (see _biochemical_per_layer()), since that function’s Brent Ci-solver was only proven correct for scalar leaf micro-environments.

SCOPE energy-balance closure loop: iterates leaf (sunlit/shaded) and soil (sunlit/shaded) temperature until sensible+latent heat flux matches net radiation, coupling radiative transfer (net_radiation_lite(), rtmt_sb()), aerodynamics (get_resistances(), monin_obukhov()), photosynthesis/fluorescence (get_biochemical()) and heat-flux partitioning (get_heatfluxes()).

Direct, “SCOPE-lite”-only port of SCOPEinR::get.ebal (SCOPEinR/R/ebal.R). Matches every reference case built during this whole port:

  • Only the empirical/default fluorescence-model branch (get.biochemical, not the alternative get.biochemical.MD12 – not ported, only used when options.Fluorescence_model$Value == 1).

  • Only the simple ground-heat-flux method (R’s SoilHeatMethod == 2, G = 0.35 * Rn – always the case for a single-timestep/non-timeseries run, i.e. options.simulation$Value != 1); the two time-series-history soil-inertia methods (0/1, needing a rolling Tsold state across timesteps) are not ported.

  • Only meanleaf.v2’s 'layers' aggregation mode (aggregator_ebal()) – the “lite” pipeline’s Tcu/Rnuc/etc are plain length-nl vectors throughout (one value per canopy layer, no per-leaf-angle-class detail), so the full (13,36,nl) 'angles'/'angles_and_layers' modes never apply.

class scopeinpython.ebal.EbalMeteo(Ta: 'float', ea: 'float', Ca: 'float', p: 'float', u: 'float', z: 'float')[source]

Bases: object

Parameters:

  • Ta (float)

  • ea (float)

  • Ca (float)

  • p (float)

  • u (float)

  • z (float)

Ta: float
ea: float
Ca: float
p: float
u: float
z: float
class scopeinpython.ebal.EbalCanopyParams(Cd, rwc, z0m, d, hc, leafwidth, kV)[source]

Bases: object

Aerodynamic/structural canopy properties beyond CanopyStructure needed by the resistance scheme and the Vcmax vertical profile.

Parameters:

  • Cd (float)

  • rwc (float)

  • z0m (float)

  • d (float)

  • hc (float)

  • leafwidth (float)

  • kV (float)

Cd: float
rwc: float
z0m: float
d: float
hc: float
leafwidth: float
kV: float
class scopeinpython.ebal.EbalSoilParams(rbs: 'float', rss: 'float', rs_thermal: 'float')[source]

Bases: object

Parameters:

  • rbs (float)

  • rss (float)

  • rs_thermal (float)

rbs: float
rss: float
rs_thermal: float
class scopeinpython.ebal.EbalResult(counter: 'int', Tcu: 'np.ndarray', Tch: 'np.ndarray', Tsu: 'float', Tsh: 'float', bcu: 'BiochemResult', bch: 'BiochemResult', canopyemis: 'float', Rnctot: 'float', lEctot: 'float', Hctot: 'float', Actot: 'float', Tcave: 'float', Rnstot: 'float', lEstot: 'float', Hstot: 'float', Gtot: 'float', Tsave: 'float', Rntot: 'float', lEtot: 'float', Htot: 'float', maxEBercu: 'float', maxEBerch: 'float', maxEBers: 'float')[source]

Bases: object

Parameters:

  • counter (int)

  • Tcu (ndarray)

  • Tch (ndarray)

  • Tsu (float)

  • Tsh (float)

  • bcu (BiochemResult)

  • bch (BiochemResult)

  • canopyemis (float)

  • Rnctot (float)

  • lEctot (float)

  • Hctot (float)

  • Actot (float)

  • Tcave (float)

  • Rnstot (float)

  • lEstot (float)

  • Hstot (float)

  • Gtot (float)

  • Tsave (float)

  • Rntot (float)

  • lEtot (float)

  • Htot (float)

  • maxEBercu (float)

  • maxEBerch (float)

  • maxEBers (float)

counter: int
Tcu: ndarray
Tch: ndarray
Tsu: float
Tsh: float
bcu: BiochemResult
bch: BiochemResult
canopyemis: float
Rnctot: float
lEctot: float
Hctot: float
Actot: float
Tcave: float
Rnstot: float
lEstot: float
Hstot: float
Gtot: float
Tsave: float
Rntot: float
lEtot: float
Htot: float
maxEBercu: float
maxEBerch: float
maxEBers: float
scopeinpython.ebal.aggregator_ebal(LAI, sunlit_flux, shaded_flux, Fs, nl)[source]

LAI-scaled canopy-integrated total flux, combining sunlit (weighted by Fs) and shaded (weighted by 1 - Fs) leaf-scale contributions. Direct port of SCOPEinR::get.aggregator.ebal + meanleaf.v2, 'layers' mode only (see module docstring).

Parameters:
Return type:

float

scopeinpython.ebal.ebal(spectral, rtmo, canopy, ebal_canopy, meteo, soil, rho_thermal, tau_thermal, leaf_refl, leaf_tran, rsoil, kChlrel, leafbio, leaf_emis, tts, lazitab, use_monin_obukhov=True, k_maxit=100, maxEBer=1.0)[source]

Direct port of SCOPEinR::get.ebal (“SCOPE-lite” only, see module docstring).

Parameters:

  • rtmo (RTMoResult) – From scopeinpython.rtmo.run_rtmo(), same canopy/geometry as elsewhere here.

  • leaf_refl (array_like) – Same leaf/soil optics passed to run_rtmo (400-2400nm, 2001 points; leaf_refl/leaf_tran may be (nl, 2001) or (2001,)).

  • leaf_tran (array_like) – Same leaf/soil optics passed to run_rtmo (400-2400nm, 2001 points; leaf_refl/leaf_tran may be (nl, 2001) or (2001,)).

  • rsoil (array_like) – Same leaf/soil optics passed to run_rtmo (400-2400nm, 2001 points; leaf_refl/leaf_tran may be (nl, 2001) or (2001,)).

  • kChlrel (array_like, shape (nl, 2001) or (2001,)) – See scopeinpython.rtmo.net_radiation_lite().

  • leafbio (LeafBio) – TDP must be populated for temperature-corrected biochemistry (matches how every biochemistry reference case in this port is built).

  • leaf_emis (float) – Leaf thermal-IR emissivity (data.leafbio$emis in R).

  • k_maxit (int) – Maximum number of energy-balance iterations (k.maxit in R).

  • maxEBer (float) – Convergence threshold, maximum acceptable energy-balance error for any component (W/m2).

  • spectral (SpectralConfig)

  • canopy (CanopyStructure)

  • ebal_canopy (EbalCanopyParams)

  • meteo (EbalMeteo)

  • soil (EbalSoilParams)

  • rho_thermal (float)

  • tau_thermal (float)

  • tts (float)

  • lazitab (ndarray)

  • use_monin_obukhov (bool)

Return type:

EbalResult