trunx.gp3 namespace

Submodules

trunx.gp3.PG3_model_impl module

Base implementation of 3PG Model.

trunx.gp3.PG3_model_impl.prepare_data(file_path)

Prepare data and initial state for 3PG model.

trunx.gp3.PG3_model_impl.run_threepg_main(file_path, observed_data=None, plot_output=True, r_comparison=False, plot_id='', show_plots: bool = True)

Run 3PG model.

trunx.gp3.helper_function module

Helper functions to implement 3PG model.

trunx.gp3.helper_function.apply_self_thinning(params, WS: Array, N: Array, max_mortality: Array | None = None) → tuple[Array, Array]

Apply self-thinning mortality based on size-density constraints.

Parameters:

• WS (Array) – Stand stem biomass (t ha⁻¹).

• N (Array) – Stocking density (trees ha⁻¹).

• wSx (Array) – Maximum stem biomass parameter.

• max_mortality (Array, optional) – Maximum fractional mortality per timestep.

Returns:

• WS_new (Array) – Updated stem biomass after self-thinning (t ha⁻¹).

• N_new (Array) – Updated stocking density after self-thinning (trees ha⁻¹).

trunx.gp3.helper_function.apply_self_thinning_with_mortality_factors(params, WS: jax.Array, WF: jax.Array, WR: jax.Array, N: jax.Array, dormant: jax.Array) → tuple[jax.Array, jax.Array, jax.Array, jax.Array, jax.Array]

Apply self-thinning with mortality factors for stem, foliage, and roots.

trunx.gp3.helper_function.apply_stress_mortality(params, age_months: jax.Array, WS: jax.Array, WF: jax.Array, WR: jax.Array, N: jax.Array, dormant: jax.Array) → tuple[jax.Array, jax.Array, jax.Array, jax.Array, jax.Array]

Apply age-dependent stress mortality and update biomass pools.

trunx.gp3.helper_function.calculate_base_conductance(params, lai: jax.Array) → jax.Array

Calculate base canopy conductance (gC) as function of LAI.

Parameters:

• lai (Array) – LAI

• MaxCond (Array) – Maximum canopy conductance (m/s)

• MinCond (Array) – Minimum canopy conductance (m/s)

• LAIgcx (Array) – LAI at which conductance reaches maximum

Returns:

gC – Base canopy conductance (m/s)

Return type:

Array

trunx.gp3.helper_function.calculate_day_length(latitude: jax.Array, month: jax.Array) → jax.Array

Calculate day length in seconds for a given latitude and month.

Parameters:

• latitude (Array) – Latitude in degrees

• month (Array) – Current month (1-12)

Returns:

day_length – Day length in seconds

Return type:

Array

trunx.gp3.helper_function.calculate_interception(params, prcp: jax.Array, lai: jax.Array) → tuple[jax.Array, jax.Array]

Calculate rainfall interception for a single species (JAX-compatible).

Parameters:

• prcp (Array) – Monthly precipitation (mm)

• lai (Array) – Leaf Area Index

• MaxIntcptn (Array) – Maximum interception fraction

• LAImaxIntcptn (Array) – LAI at which interception reaches maximum

Returns:

• prcp_interc_fract (Array) – Interception fraction

• prcp_interc (Array) – Interception amount (mm)

trunx.gp3.helper_function.calculate_transpiration(params, solar_rad: Array, day_length: Array, VPD: Array, conduct_canopy: Array, days_in_month: Array, rhoAir: Array | None = None, lambda_v: Array | None = None, VPDconv: Array | None = None, e20: Array | None = None) → Array

Calculate transpiration using Penman-Monteith.

Returns transpiration in mm/month.

trunx.gp3.helper_function.compute_allocation_fraction(species, params, phi_phys: jax.Array, DBH: jax.Array)

Compute all allocation fractions (roots, foliage, stem) for 3-PG model.

eta_R = (r_x * r_n) / (r_n + (r_x - r_n) * m)

Parameters:

• B (Array) – Tree size (DBH in cm)

• FR (Array) – Fertility rating (0-1)

• phi_phys (Array) – Physiological modifier (0-1)

• pFS2 (Array) – Foliage:stem ratio at reference size 2 cm

• pFS20 (Array) – Foliage:stem ratio at reference size 20 cm

• pRx (Array) – Maximum root allocation ratio

• pRn (Array) – Minimum root allocation ratio

• m0 (Array, optional) – Base fertility effect parameter (default 0.5)

Returns:

• eta_R (Array) – Fraction of NPP allocated to roots

• eta_F (Array) – Fraction of NPP allocated to foliage

• eta_S (Array) – Fraction of NPP allocated to stem

• pFS (Array) – Foliage:stem ratio (intermediate value)

trunx.gp3.helper_function.compute_asw(params, site, ASW: Array, prcp: Array, solar_rad: Array, VPD: Array, day_length: Array, days_in_month: Array, conduct_canopy: Array, lai: Array, evapotra_soil: Array | None = None) → tuple[Array, Array]

Complete soil water balance for a single species following Fortran 3-PG code.

Parameters:

• ASW (Array) – Current available soil water (mm)

• prcp (Array) – Monthly precipitation (mm)

• solar_rad (Array) – Solar radiation (MJ/m²/day)

• VPD (Array) – Vapor pressure deficit (kPa)

• day_length (Array) – Day length (seconds)

• days_in_month (Array) – Number of days in the month

• conduct_canopy (Array) – Canopy conductance (m/s)

• lai (Array) – Leaf Area Index

• evapotra_soil (Array, optional) – Soil evaporation (mm), default 0.0

Returns:

• tuple[Array, Array]

• ASW – Updated available soil water

• GPP_scale_factor – Factor to scale GPP

trunx.gp3.helper_function.compute_canopy_cover(params, age: jax.Array)

Calculate fractional canopy cover.

Parameters:

• age_years (Array) – Stand age in years

• fullCanAge (Array) – Age at canopy closure (years)

Returns:

canopy_cover – Fractional canopy cover (0-1)

Return type:

Array

trunx.gp3.helper_function.compute_dbh(params, WS: jax.Array, N: jax.Array) → jax.Array

Compute DBH from stand-level values.

DBH = (WS / aWs) ** (1 / nWs)

Parameters:

• WS (Array) – Stem biomass.

• aWs (Array) – Stem biomass allometric coefficient.

• nWs (Array) – Stem biomass exponent.

Returns:

dbh – Diameter at breast height (cm).

Return type:

Array

trunx.gp3.helper_function.compute_lai(params, WF: jax.Array, age_months: jax.Array) → tuple[jax.Array, jax.Array]

Compute Leaf Area Index (LAI) from foliage biomass and stand age.

LAI is calculated using an age-dependent specific leaf area (SLA) following the 3-PG formulation:

SLA(t) = SLA0 + SLA1 * exp(-ln(2) * t / tSLA) LAI = WF * SLA(t) * 0.1

where stand age t is expressed in years.

The factor 0.1 is a unit conversion:

1 t ha⁻¹ = 1000 kg / 10,000 m² = 0.1 kg m⁻²

Multiplying foliage biomass (t ha⁻¹) by 0.1 converts it to kg m⁻².

Parameters:

• WF (Array) – Foliage biomass per unit ground area (t ha⁻¹).

• stand_age_months (Array) – Stand age (months).

• SLA0 (Array) – Minimum SLA at old age (m² kg⁻¹).

• SLA1 (Array) – Difference between maximum and minimum SLA (m² kg⁻¹).

• tSLA (Array) – Half-life for SLA decline (years).

Returns:

LAI – Leaf Area Index (m² leaf m⁻² ground).

Return type:

Array

trunx.gp3.helper_function.compute_light_interception(params, LAI: Array, canopy_cover: Array | None = None)

Compute the light interception.

Compute the fraction of incoming radiation intercepted by the canopy using the Beer-Lambert law.

Parameters:

• k (Array) – Canopy light extinction coefficient (dimensionless).

• LAI (Array) – Leaf area index (m² leaf m⁻² ground).

• canopy_cover (Array, optional) – Fractional canopy cover (0 < canopy_cover ≤ 1). Default is 1.

Returns:

lightIntcptn – Fraction of incident radiation intercepted by the canopy (0-1).

Return type:

Array

trunx.gp3.helper_function.compute_litterfall_rate(age_months: jax.Array, gammaF0: jax.Array, gammaF1: jax.Array, tgammaF: jax.Array) → jax.Array

Compute foliage litterfall rate as a function of stand age.

Parameters:

• age_months (Array) – Stand age (months).

• gammaF0 (Array) – Litterfall rate at young age.

• gammaF1 (Array) – Minimum litterfall rate at old age.

• tgammaF (Array) – Characteristic age controlling litterfall decline (months).

Returns:

gammaF – Foliage litterfall rate.

Return type:

Array

trunx.gp3.helper_function.f_age(params, age_months: jax.Array) → jax.Array

Age-related growth modifier.

The function is defined as:

f_age = 1 / (1 + (FAge / rAge) ** nAge)

where:

FAge = (stand age in years) / MaxAge

Parameters:

• age_months (Array) – Stand age in months.

• MaxAge (Array) – Maximum stand age used to scale relative age (years).

• nAge (Array) – Shape parameter controlling the steepness of the age-related decline. Higher values produce a sharper decline.

• rAge (Array, optional) – Relative age at which f_age equals 0.5 (default = 0.95).

Returns:

F_age – Age modifier ranging from 0 to 1.

Return type:

Array

trunx.gp3.helper_function.f_calpha(params, co2: jax.Array)

CO2 modifier for photosynthesis (alpha).

Parameters:

• co2 (Array) – Atmospheric CO2 concentration (ppm)

• fCalphax (Array) – CO2 modifier parameter for photosynthesis

Returns:

f_calpha – CO2 modifier for photosynthesis

Return type:

Array

trunx.gp3.helper_function.f_cg(params, co2: jax.Array) → jax.Array

CO2 modifier for canopy conductance.

Parameters:

• co2 (Array) – Atmospheric CO2 concentration (ppm)

• fCg0 (Array) – CO2 modifier parameter for conductance

Returns:

f_cg – CO2 modifier for canopy conductance

Return type:

Array

trunx.gp3.helper_function.f_exp_foliage(params, age_months: jax.Array) → jax.Array

Exponential foliage growth function.

Parameters:

• x (Array) – Input array (typically time in months).

• gammaF1 (Array) – Final/asymptotic value (maximum foliage biomass).

• gammaF0 (Array) – Initial value (initial foliage biomass).

• tgammaF (Array) – Time to reach a certain growth stage (months).

Returns:

out

Return type:

Array

trunx.gp3.helper_function.f_exp_wood(params, age_months: jax.Array) → jax.Array

Exponential wood density function.

trunx.gp3.helper_function.f_frost(params, frost_days: jax.Array, days_in_month: jax.Array) → jax.Array

Calculate the frost response function (fF) for forest growth.

The function is defined as:

fF = 1 - kF * frost_days / days_in_month

Parameters:

• frost_days (Array) – Number of frost days in a month.

• days_in_month (Array) – Number of days in the current month.

Returns:

Frost response function value (fF).

Return type:

Array

trunx.gp3.helper_function.f_nutrition(species, params) → jax.Array

Soil nutrition modifier from the 3-PG model.

f_N = 1 - (1 - fN0) * (1 - FR)**fNn with fNn = 0 -> f_N = 1

Parameters:

• fertility (Array) – Soil fertility index (0-1).

• fN0 (Array) – Minimum modifier at zero fertility.

• fNn (Array) – Nutrition response exponent.

Returns:

f_N – Nutrition modifier.

Return type:

Array

trunx.gp3.helper_function.f_soil_water(ASW: jax.Array, site, params) → jax.Array

Soil water stress function.

The function is defined as:

SWdef = 1 - ASW / ASW_max

f_sw = 1 / [ 1 + (SWdef / SWconst)^SWpower ]

Parameters:

• ASW (Array) – Available soil water.

• ASW_max (Array) – Maximum available soil water.

• SWconst (Array) – Scaling constant controlling stress onset.

• SWpower (Array) – Exponent controlling stress sensitivity.

Returns:

f_sw – Soil water stress factor clipped to [0, 1].

Return type:

Array

trunx.gp3.helper_function.f_temperature(params, T_avg: jax.Array) → jax.Array

Calculate the temperature response function (fT) for forest growth.

The function is defined as: f_T = ((T - Tmin)/(Topt - Tmin)) *

((Tmax - T)/(Tmax - Topt))^((Tmax - Topt)/(Topt - Tmin))

Parameters:

• T (Array) – Current temperature (monthly mean temperature).

• Tmin (Array) – Minimum temperature for growth.

• Topt (Array) – Optimum temperature for growth.

• Tmax (If T <= Tmin or T >=) – Maximum temperature for growth.

• Tmax

• 0. (fT is set to)

Returns:

Temperature response function value (fT).

Return type:

jax.Array

trunx.gp3.helper_function.f_temperature_gc(params, T_avg: jax.Array, T_max: jax.Array) → jax.Array

Temperature response function for canopy conductance.

Uses (T_avg + T_max)/2 instead of just T_avg.

Parameters:

• T_avg (Array) – Average monthly temperature (°C)

• T_max (Array) – Maximum monthly temperature (°C)

• Tmin (Array) – Minimum temperature for growth (°C)

• Topt (Array) – Optimum temperature for growth (°C)

• Tmax (Array) – Maximum temperature for growth (°C)

Returns:

f_tmp_gc – Temperature modifier for canopy conductance (0-1)

Return type:

Array

trunx.gp3.helper_function.f_vpd(VPD: jax.Array, CoeffCond: jax.Array) → jax.Array

Calculate the vapor pressure deficit response function (fVPD).

The function is defined as: f_VPD = exp(-CoeffCond * VPD) # CoeffCond = k_g (Landsberg and Warin 1997)

Parameters:

• VPD (Array) – Vapor pressure deficit in kPa.

• CoeffCond (Array) – Threshold for the vapor pressure deficit that significantly affects growth.

Returns:

Vapor pressure deficit response function value (fVPD).

Return type:

Array

trunx.gp3.helper_function.is_dormant(month: jax.Array, leafgrow: jax.Array, leaffall: jax.Array) → jax.Array

Determine if current month is in dormant period.

Parameters:

• month (Array) – Current month (1-12)

• leafgrow (Array) – Month when leaves start growing

• leaffall (Array) – Month when leaves start falling

Returns:

dormant – True if dormant period, False otherwise

Return type:

Array

trunx.gp3.helper_function.scale_transpiration(transp_veg: jax.Array, evapotra_soil: jax.Array, prcp_interc: jax.Array, evapo_transp: jax.Array, f_transp_scale: jax.Array) → tuple[jax.Array, jax.Array]

Scale transpiration and evaporation when water-limited.

trunx.gp3.helper_function.update_soil_water(site, ASW: Array, prcp: Array, transp_veg: Array, evapotra_soil: Array, prcp_interc: Array, Irrig: Array | None = None, water_runoff_polled: Array | None = None, poolFractn: Array | None = None) → tuple[Array, Array, Array]

Update soil water balance.

trunx.gp3.model_inputs module

Class definition for data.

class trunx.gp3.model_inputs.ClimateData(T_avg: jax.numpy.ndarray, T_max: jax.numpy.ndarray, VPD: jax.numpy.ndarray, precip: jax.numpy.ndarray, solar_rad: jax.numpy.ndarray, frost_days: jax.numpy.ndarray, n_days: jax.numpy.ndarray, co2: jax.numpy.ndarray, d13catm: jax.numpy.ndarray, month: jax.numpy.ndarray)

Bases: NamedTuple

Climate data information.

T_avg: jax.numpy.ndarray

Alias for field number 0

T_max: jax.numpy.ndarray

Alias for field number 1

VPD: jax.numpy.ndarray

Alias for field number 2

co2: jax.numpy.ndarray

Alias for field number 7

d13catm: jax.numpy.ndarray

Alias for field number 8

frost_days: jax.numpy.ndarray

Alias for field number 5

month: jax.numpy.ndarray

Alias for field number 9

n_days: jax.numpy.ndarray

Alias for field number 6

precip: jax.numpy.ndarray

Alias for field number 3

solar_rad: jax.numpy.ndarray

Alias for field number 4

class trunx.gp3.model_inputs.Params(pFS2: jax.numpy.ndarray, pFS20: jax.numpy.ndarray, aWS: jax.numpy.ndarray, nWS: jax.numpy.ndarray, pRx: jax.numpy.ndarray, pRn: jax.numpy.ndarray, gammaF1: jax.numpy.ndarray, gammaF0: jax.numpy.ndarray, tgammaF: jax.numpy.ndarray, gammaR: jax.numpy.ndarray, leafgrow: jax.numpy.ndarray, leaffall: jax.numpy.ndarray, Tmin: jax.numpy.ndarray, Topt: jax.numpy.ndarray, Tmax: jax.numpy.ndarray, kF: jax.numpy.ndarray, SWconst: jax.numpy.ndarray, SWpower: jax.numpy.ndarray, fCalpha700: jax.numpy.ndarray, fCg700: jax.numpy.ndarray, m0: jax.numpy.ndarray, fN0: jax.numpy.ndarray, fNn: jax.numpy.ndarray, MaxAge: jax.numpy.ndarray, nAge: jax.numpy.ndarray, rAge: jax.numpy.ndarray, gammaN1: jax.numpy.ndarray, gammaN0: jax.numpy.ndarray, tgammaN: jax.numpy.ndarray, ngammaN: jax.numpy.ndarray, wSx1000: jax.numpy.ndarray, thinPower: jax.numpy.ndarray, mF: jax.numpy.ndarray, mR: jax.numpy.ndarray, mS: jax.numpy.ndarray, SLA0: jax.numpy.ndarray, SLA1: jax.numpy.ndarray, tSLA: jax.numpy.ndarray, k: jax.numpy.ndarray, fullCanAge: jax.numpy.ndarray, MaxIntcptn: jax.numpy.ndarray, LAImaxIntcptn: jax.numpy.ndarray, cVPD: jax.numpy.ndarray, alphaCx: jax.numpy.ndarray, Y: jax.numpy.ndarray, MinCond: jax.numpy.ndarray, MaxCond: jax.numpy.ndarray, LAIgcx: jax.numpy.ndarray, CoeffCond: jax.numpy.ndarray, BLcond: jax.numpy.ndarray, RGcGw: jax.numpy.ndarray, D13CTissueDif: jax.numpy.ndarray, aFracDiffu: jax.numpy.ndarray, bFracRubi: jax.numpy.ndarray, fracBB0: jax.numpy.ndarray, fracBB1: jax.numpy.ndarray, tBB: jax.numpy.ndarray, rhoMin: jax.numpy.ndarray, rhoMax: jax.numpy.ndarray, tRho: jax.numpy.ndarray, crownshape: jax.numpy.ndarray, aH: jax.numpy.ndarray, nHB: jax.numpy.ndarray, nHC: jax.numpy.ndarray, aV: jax.numpy.ndarray, nVB: jax.numpy.ndarray, nVH: jax.numpy.ndarray, nVBH: jax.numpy.ndarray, aK: jax.numpy.ndarray, nKB: jax.numpy.ndarray, nKH: jax.numpy.ndarray, nKC: jax.numpy.ndarray, nKrh: jax.numpy.ndarray, aHL: jax.numpy.ndarray, nHLB: jax.numpy.ndarray, nHLL: jax.numpy.ndarray, nHLC: jax.numpy.ndarray, nHLrh: jax.numpy.ndarray, Qa: jax.numpy.ndarray, Qb: jax.numpy.ndarray, gDM_mol: jax.numpy.ndarray, molPAR_MJ: jax.numpy.ndarray)

Bases: NamedTuple

Parameter information.

BLcond: jax.numpy.ndarray

Alias for field number 49

CoeffCond: jax.numpy.ndarray

Alias for field number 48

D13CTissueDif: jax.numpy.ndarray

Alias for field number 51

LAIgcx: jax.numpy.ndarray

Alias for field number 47

LAImaxIntcptn: jax.numpy.ndarray

Alias for field number 41

MaxAge: jax.numpy.ndarray

Alias for field number 23

MaxCond: jax.numpy.ndarray

Alias for field number 46

MaxIntcptn: jax.numpy.ndarray

Alias for field number 40

MinCond: jax.numpy.ndarray

Alias for field number 45

Qa: jax.numpy.ndarray

Alias for field number 78

Qb: jax.numpy.ndarray

Alias for field number 79

RGcGw: jax.numpy.ndarray

Alias for field number 50

SLA0: jax.numpy.ndarray

Alias for field number 35

SLA1: jax.numpy.ndarray

Alias for field number 36

SWconst: jax.numpy.ndarray

Alias for field number 16

SWpower: jax.numpy.ndarray

Alias for field number 17

Tmax: jax.numpy.ndarray

Alias for field number 14

Tmin: jax.numpy.ndarray

Alias for field number 12

Topt: jax.numpy.ndarray

Alias for field number 13

Y: jax.numpy.ndarray

Alias for field number 44

aFracDiffu: jax.numpy.ndarray

Alias for field number 52

aH: jax.numpy.ndarray

Alias for field number 61

aHL: jax.numpy.ndarray

Alias for field number 73

aK: jax.numpy.ndarray

Alias for field number 68

aV: jax.numpy.ndarray

Alias for field number 64

aWS: jax.numpy.ndarray

Alias for field number 2

alphaCx: jax.numpy.ndarray

Alias for field number 43

bFracRubi: jax.numpy.ndarray

Alias for field number 53

cVPD: jax.numpy.ndarray

Alias for field number 42

crownshape: jax.numpy.ndarray

Alias for field number 60

fCalpha700: jax.numpy.ndarray

Alias for field number 18

fCg700: jax.numpy.ndarray

Alias for field number 19

fN0: jax.numpy.ndarray

Alias for field number 21

fNn: jax.numpy.ndarray

Alias for field number 22

fracBB0: jax.numpy.ndarray

Alias for field number 54

fracBB1: jax.numpy.ndarray

Alias for field number 55

fullCanAge: jax.numpy.ndarray

Alias for field number 39

gDM_mol: jax.numpy.ndarray

Alias for field number 80

gammaF0: jax.numpy.ndarray

Alias for field number 7

gammaF1: jax.numpy.ndarray

Alias for field number 6

gammaN0: jax.numpy.ndarray

Alias for field number 27

gammaN1: jax.numpy.ndarray

Alias for field number 26

gammaR: jax.numpy.ndarray

Alias for field number 9

k: jax.numpy.ndarray

Alias for field number 38

kF: jax.numpy.ndarray

Alias for field number 15

leaffall: jax.numpy.ndarray

Alias for field number 11

leafgrow: jax.numpy.ndarray

Alias for field number 10

m0: jax.numpy.ndarray

Alias for field number 20

mF: jax.numpy.ndarray

Alias for field number 32

mR: jax.numpy.ndarray

Alias for field number 33

mS: jax.numpy.ndarray

Alias for field number 34

molPAR_MJ: jax.numpy.ndarray

Alias for field number 81

nAge: jax.numpy.ndarray

Alias for field number 24

nHB: jax.numpy.ndarray

Alias for field number 62

nHC: jax.numpy.ndarray

Alias for field number 63

nHLB: jax.numpy.ndarray

Alias for field number 74

nHLC: jax.numpy.ndarray

Alias for field number 76

nHLL: jax.numpy.ndarray

Alias for field number 75

nHLrh: jax.numpy.ndarray

Alias for field number 77

nKB: jax.numpy.ndarray

Alias for field number 69

nKC: jax.numpy.ndarray

Alias for field number 71

nKH: jax.numpy.ndarray

Alias for field number 70

nKrh: jax.numpy.ndarray

Alias for field number 72

nVB: jax.numpy.ndarray

Alias for field number 65

nVBH: jax.numpy.ndarray

Alias for field number 67

nVH: jax.numpy.ndarray

Alias for field number 66

nWS: jax.numpy.ndarray

Alias for field number 3

ngammaN: jax.numpy.ndarray

Alias for field number 29

pFS2: jax.numpy.ndarray

Alias for field number 0

pFS20: jax.numpy.ndarray

Alias for field number 1

pRn: jax.numpy.ndarray

Alias for field number 5

pRx: jax.numpy.ndarray

Alias for field number 4

rAge: jax.numpy.ndarray

Alias for field number 25

rhoMax: jax.numpy.ndarray

Alias for field number 58

rhoMin: jax.numpy.ndarray

Alias for field number 57

tBB: jax.numpy.ndarray

Alias for field number 56

tRho: jax.numpy.ndarray

Alias for field number 59

tSLA: jax.numpy.ndarray

Alias for field number 37

tgammaF: jax.numpy.ndarray

Alias for field number 8

tgammaN: jax.numpy.ndarray

Alias for field number 28

thinPower: jax.numpy.ndarray

Alias for field number 31

wSx1000: jax.numpy.ndarray

Alias for field number 30

class trunx.gp3.model_inputs.SiteData(latitude: jax.numpy.ndarray, altitude: jax.numpy.ndarray, soil_class: jax.numpy.ndarray, ASW: jax.numpy.ndarray, ASW_max: jax.numpy.ndarray, ASW_min: jax.numpy.ndarray, year_i: jax.numpy.ndarray, month_i: jax.numpy.ndarray)

Bases: NamedTuple

Site data information.

ASW: jax.numpy.ndarray

Alias for field number 3

ASW_max: jax.numpy.ndarray

Alias for field number 4

ASW_min: jax.numpy.ndarray

Alias for field number 5

altitude: jax.numpy.ndarray

Alias for field number 1

latitude: jax.numpy.ndarray

Alias for field number 0

month_i: jax.numpy.ndarray

Alias for field number 7

soil_class: jax.numpy.ndarray

Alias for field number 2

year_i: jax.numpy.ndarray

Alias for field number 6

class trunx.gp3.model_inputs.SpeciesData(specie: jax.numpy.ndarray, FR: jax.numpy.ndarray, WF: jax.numpy.ndarray, WR: jax.numpy.ndarray, WS: jax.numpy.ndarray, N: jax.numpy.ndarray, year_p: jax.numpy.ndarray, month_p: jax.numpy.ndarray)

Bases: NamedTuple

Species data information.

FR: jax.numpy.ndarray

Alias for field number 1

N: jax.numpy.ndarray

Alias for field number 5

WF: jax.numpy.ndarray

Alias for field number 2

WR: jax.numpy.ndarray

Alias for field number 3

WS: jax.numpy.ndarray

Alias for field number 4

month_p: jax.numpy.ndarray

Alias for field number 7

specie: jax.numpy.ndarray

Alias for field number 0

year_p: jax.numpy.ndarray

Alias for field number 6

class trunx.gp3.model_inputs.State(WF: jax.numpy.ndarray, WR: jax.numpy.ndarray, WS: jax.numpy.ndarray, N: jax.numpy.ndarray, ASW: jax.numpy.ndarray, age: jax.numpy.ndarray, WF_debt: jax.numpy.ndarray, prev_month: jax.numpy.ndarray)

Bases: NamedTuple

State information.

ASW: jax.numpy.ndarray

Alias for field number 4

N: jax.numpy.ndarray

Alias for field number 3

WF: jax.numpy.ndarray

Alias for field number 0

WF_debt: jax.numpy.ndarray

Alias for field number 6

WR: jax.numpy.ndarray

Alias for field number 1

WS: jax.numpy.ndarray

Alias for field number 2

age: jax.numpy.ndarray

Alias for field number 5

prev_month: jax.numpy.ndarray

Alias for field number 7

trunx.gp3.plot_function module

Plot functions to visualize outputs and its comparison with r3PG.

trunx.gp3.plot_function.create_comparison_dataframe(r_df, outputs, start_month, species_list)

Create a polars DataFrame combining R 3-PG outputs and python implementation results.

Parameters:

• r_df (pl.DataFrame) – polars DataFrame from R with columns: date, variable, value, species

• outputs (Dict) – dict of original outputs like {“WS”: array, “DBH”: array, …}

• start_month (datetime) – numpy datetime64 for start (e.g., np.datetime64(‘2000-01’))

Returns:

Combined DataFrame of R and Python outputs.

Return type:

pl.DataFrame

trunx.gp3.plot_function.plot_combined_3pg_outputs(r_df, outputs, start_month, species_list, fig_name: str | None = None)

Visualize both R 3-PG outputs and python implementation in the same plot.

Parameters:

• r_df (pl.DataFrame) – polars DataFrame from R with columns: date, variable, value, species

• outputs (Dict) – dict of original outputs like {“WS”: array, “DBH”: array, …}

• start_month (datetime) – numpy datetime64 for start (e.g., np.datetime64(‘2000-01-01’))

• fig_name (str) – name to save figure

trunx.gp3.plot_function.plot_combined_3pg_outputs_obv(df, plot_metrics=None, observed_data=None, fig_name=None, plot_id='', show: bool = True)

Visualize R and Python 3PG implementations with observed data.

trunx.gp3.plot_function.plot_combined_3pg_outputs_per_species(r_df, outputs, start_month, species_list, fig_name: str | None = None)

Visualize both R 3-PG outputs and python implementation in the same plot.

Parameters:

• r_df (pl.DataFrame) – polars DataFrame from R with columns: date, variable, value, species

• outputs (Dict) – dict of original outputs like {“WS”: array, “DBH”: array, …}

• start_month (datetime) – numpy datetime64 for start (e.g., np.datetime64(‘2000-01-01’))

• fig_name (str) – name to save figure

trunx.gp3.plot_function.plot_dbh_distribution(plot_id: str, file_path: str = '/home/runner/work/TrunX/TrunX/data/clean/icp_tree_data.parquet', kind: str = 'box', fig_name: str | None = None, show: bool = True) → list[Figure]

Plot per-tree DBH distribution over survey dates with key stand statistics.

Parameters:

• icp_df (pl.DataFrame) – Tree-level ICP data with specie, date and dbh_cm columns.

• kind (str) – “box” for a boxplot of tree diameters per survey date, or “scatter” for individual tree diameters plotted per date.

• fig_name (str | None) – Base name used to save each species’ figure under ./images/.

• show (bool) – Whether to call plt.show().

Returns:

One figure per species, each showing the diameter distribution alongside its coefficient of variation, arithmetic and quadratic (QMD) mean, and skewness over time.

Return type:

list[Figure]

trunx.gp3.plot_function.plot_outputs(outputs, start_month, fig_name: str | None = None, show: bool = True)

Visualize key 3-PG state variables over time.

trunx.gp3.plot_function.plot_weather_data(clean_wdf, plot_id)

Visualize weather data with missing value periods highlighted.

trunx.gp3.prepare_climate module

Prepare climate data for 3PG model.

trunx.gp3.prepare_climate.clim_range(climate)

Check whether climate data are within plausible ranges.

trunx.gp3.prepare_climate.get_vpd(tmin, tmax)

Calculate daytime vapor pressure deficit (VPD).

trunx.gp3.prepare_climate.prepare_climate(climate, from_='2001-01', to='2010-11')

Prepare climate table for 3-PG simulation.

trunx.gp3.prepare_site module

Prepare site data for 3PG model.

trunx.gp3.prepare_site.prepare_site(site: DataFrame) → tuple[SiteData, datetime64, datetime64]

Check the site data for consistency.

trunx.gp3.prepare_species module

Prepare species data for 3PG model.

trunx.gp3.prepare_species.prepare_species(species: DataFrame) → SpeciesData

Check the species data for consistency.

trunx.gp3.run_3pg module

Run the 3PG model.

trunx.gp3.run_3pg.loss_fn(log_params_arr, fixed_params, s0, climate, site, obs_WS, obs_times, species)

MSE loss for gradient-based calibration.

log_params_arr:

[log(alphaCx), log(CoeffCond), logit(Y)]

trunx.gp3.run_3pg.model_step(state, climate_month, params, site, species)

Compute one model step.

trunx.gp3.run_3pg.run_3pg(initial_state, climate, params, site, species)

Run 3PG model.

trunx.gp3.run_3pg.ws_final(alphaCx, CoeffCond, Y_val, params, initial_state, climate, site, species)

Compute final stem biomass as a scalar function.

trunx.gp3.run_3pg.ws_final_vector(params_vec, params, initial_state, climate, site, species)

Compute final stem biomass for all species with params as a vector.

trunx.gp3.weather_processing module

Build and gap-fill monthly ICP weather data for the 3PG model.

trunx.gp3.weather_processing.aggregate_icp_monthly(df: DataFrame, plot_id: str) → DataFrame

Aggregate raw ICP weather records to monthly values for one plot.

Performs no ERA5 gap-filling — a metric is null for months where ICP has no observations of it.

Parameters:

• df (pl.DataFrame) – Raw ICP weather data with columns plot_id, code_variable, year, month, daily_mean, daily_min, daily_max.

• plot_id (str) – Plot identifier to aggregate.

Returns:

Monthly ICP weather with columns year, month, tmp_ave, tmp_min, tmp_max, frost_days, prcp, srad.

Return type:

pl.DataFrame

trunx.gp3.weather_processing.create_weather_input(df: DataFrame, plot_id: str) → tuple[list, DataFrame]

Create weather data input for 3PG model.

Any of temperature, precipitation, or solar radiation entirely missing from the ICP data is filled from ERA5 reanalysis for the same plot.

trunx.gp3.weather_processing.fill_weather_with_era5(weather_df: DataFrame, plot_id: str, start_year: int) → tuple[list, DataFrame]

Fill missing monthly weather with ERA5 reanalysis data.

Ensures the weather series starts at start_year and has no gaps, filling any months missing from ICP data — whether at the start of the series or within it — using ERA5 weather already processed for the plot location.

Parameters:

• weather_df (pl.DataFrame) – Monthly ICP weather data with columns year, month, tmp_ave, tmp_min, tmp_max, frost_days, prcp, srad.

• plot_id (str) – Plot identifier used to look up the matching ERA5 grid point.

• start_year (int) – First year the weather series must cover.

Returns:

Months still missing after filling with ERA5 (empty if none), and the resulting weather data sorted by year and month.

Return type:

tuple[list, pl.DataFrame]

trunx.gp3.weather_processing.weather_summary(weather_df)

Summarize weather data.