GitHub

API Reference

Climate Models

Biome.runmodel — Function
runmodel(m::Union{BIOME4Model, BIOMEDominanceModel, BaseModel}, vars_in::NamedTuple; 
pftlist, biome_assignment) where {T<:Real,U<:Int}

Execute the complete mechanistic model simulation for a single grid cell.

This function orchestrates the entire modeling workflow including: climate data processing, snow dynamics, soil temperature calculation, potential evapotranspiration, phenology, plant functional type constraints, NPP optimization, and biome classification.

source
runmodel(m::ThornthwaiteModel, vars_in::Vector{Union{T, U}}, args...; kwargs...) where {T <: Real, U <: Int}

Compute Thornthwaite climate classification zones from monthly temperature and precipitation data.

Arguments

  • m::ThornthwaiteModel The model instance (not directly used in this implementation, provided for dispatch).
  • vars_in::Vector{Union{T, U}} A length‑28 vector containing:
    1. Elements 1–4: (unused placeholders)
    2. Elements 5–16: twelve monthly mean temperatures (Real values)
    3. Elements 17–28: twelve monthly total precipitations (Real values)

Returns

  • output::Vector{Any} A vector of length 50 (initialized to zeros of type T), where:
    • output[1] is an Int code for the temperature zone:
      1. Tropical
      2. Mesothermal
      3. Microthermal
      4. Taiga
      5. Tundra
      6. Frost
    • output[2] is an Int code for the moisture zone:
      1. Wet
      2. Humid
      3. Subhumid
      4. Semiarid
      5. Arid
    • All other entries remain zero.
source
runmodel(m::WissmannModel, vars_in::Vector{<:Union{<:Real,<:Int}}, args...; kwargs...)

Classify climate by the Wissmann scheme using 12 months of temperature and precipitation.

Arguments

  • m::WissmannModel Model instance (for dispatch).
  • vars_in::Vector{Union{T,U}} Length‑28 vector where:
    • indices 5–16: monthly mean temperatures
    • indices 17–28: monthly precipitation totals
  • args..., kwargs... Ignored extras.

Returns

  • output::Vector{Int} (length 1) Single-element vector holding the integer code (1–22) of the matched Wissmann zone.

Notes

  • Computes seasonal totals, mean, min/max temperatures.
  • Determines hemisphere to compare winter vs summer precipitation.
  • Applies tiered thresholds for Polar, Boreal, Temperate, and Tropical groups.
source

Mechanistic Model

Base functions

Biome.PFTClassification — Type

Structure that holds the PFTs passed together to the model. The PFTs will be evaluated by the mechanistic model and put into competition to determine the dominant biome.

source
Biome.assign_biome — Function
assign_biome(optpft::AbstractNeedleleafEvergreenPFT)

Assign biome for AbstractNeedleleafEvergreenPFT plant functional type.

Returns NeedleleafEvergreenForest.

source
assign_biome(optpft::BroadleafEvergreenBase)

Assign biome for BroadleafEvergreenBase plant functional type.

Returns BroadleafEvergreenForest.

source
assign_biome(optpft::NeedleleafDeciduousBase)

Assign biome for NeedleleafDeciduousBase plant functional type.

Returns NeedleleafDeciduousForest.

source
assign_biome(optpft::BroadleafDeciduousBase)

Assign biome for BroadleafDeciduousBase plant functional type.

Returns BroadleafDeciduousForest.

source
assign_biome(optpft::AbstractC3GrassPFT)

Assign biome for C3GrassBase plant functional type.

Returns C3Grassland.

source
assign_biome(optpft::AbstractC4GrassPFT)

Assign biome for C4GrassBase plant functional type.

Returns C4Grassland.

source
assign_biome(optpft::Union{None, Default})

Assign biome for None/Default plant functional type.

Returns Desert biomes.

source
Biome.c4photo — Function
c4photo(ratio, dsun, daytime, temp, age, fpar, p, ca, pft)::Tuple{T,T,T}

Calculate C4 photosynthesis based on environmental and plant functional type (PFT) parameters.

Arguments:

  • ratio: The ratio of intercellular to ambient CO2 concentration.
  • dsun: Daily solar radiation (MJ/m²/day).
  • daytime: Length of the day (hours).
  • temp: Air temperature (°C).
  • age: Leaf age (months).
  • fpar: Fraction of photosynthetically active radiation absorbed by the canopy.
  • p: Atmospheric pressure (kPa).
  • ca: Ambient CO2 concentration (ppm).
  • pft: Plant Functional Type (integer index).

Returns:

  • leafresp: Leaf respiration rate.
  • grossphot: Gross photosynthesis rate.
  • aday: Net daily photosynthesis.
source
Biome.calcphi — Function
calcphi(gpp::AbstractVector{T})::T

Calculate the maximum quantum yield of photosynthesis based on GPP data.

Arguments

  • gpp: An array of 12 T values representing Gross Primary Productivity for each month.

Returns

  • phi: The calculated maximum quantum yield of photosynthesis.
source
Biome.constraints — Function
constraints(tcm, twm, tminin, gdd5, rad0, gdd0, maxdepth, pftlist, pftstates)

Calculate constraints for biome classification based on temperature, GDD, and other parameters. Sets each PFT’s present flag in states.

Arguments

  • tcm: Temperature of coldest month (°C)
  • twm: Temperature of warmest month (°C)
  • tminin: Minimum temperature (°C)
  • gdd5: Growing degree days above 5°C
  • rad0: Annual radiation (MJ/m²/year) # (not used here, but kept for interface consistency)
  • gdd0: Growing degree days above 0°C
  • maxdepth: Maximum snow depth (mm)
  • pftlist: List of plant functional types to evaluate
  • pftstates: Dict mapping each AbstractPFT to its PFTState

Returns

  • tmin: Adjusted minimum temperature (°C)
  • pftlist: (unchanged) PFT list
source
Biome.daily_interp! — Function
daily_interp!(dly, mly)

Fully allocation-free. Caller provides a 365-element workspace dly.

source
Biome.findnpp — Function
findnpp(pft, annp, dtemp, sun, temp, dprec, dmelt, dpet, dayl, k, dphen, co2, p, tsoil)

Find optimal Net Primary Productivity (NPP) for a plant functional type.

This function runs an NPP optimization model for one PFT by iteratively testing different leaf area index (LAI) values to find the combination that maximizes NPP. Uses a binary search approach to converge on the optimal LAI.

Arguments

  • pft: Plant Functional Type to optimize
  • annp: Annual precipitation (mm)
  • dtemp: Daily temperature array (365 elements, °C)
  • sun: Monthly solar radiation array (12 elements, MJ/m²/day)
  • temp: Monthly temperature array (12 elements, °C)
  • dprec: Daily precipitation array (365 elements, mm)
  • dmelt: Daily snowmelt array (365 elements, mm)
  • dpet: Daily potential evapotranspiration array (365 elements, mm)
  • dayl: Monthly day length array (12 elements, hours)
  • k: Soil and canopy parameter array
  • dphen: Daily phenology array (365x2 matrix)
  • co2: Atmospheric CO2 concentration (ppm)
  • p: Atmospheric pressure (kPa)
  • tsoil: Monthly soil temperature array (12 elements, °C)

Returns

A tuple containing:

  • pft: The input plant functional type (potentially modified)
  • optlai: Optimal leaf area index that maximizes NPP
  • optnpp: Maximum net primary productivity achieved (gC/m²/year)
  • pftstates: Updated PFT state

Notes

  • Returns (pft, 0.0, 0.0, pftstates) if the PFT is not present in the current conditions
  • Uses 8 iterations of binary search to converge on optimal LAI
  • Tests LAI values between 0.01 and 8.0
  • Calls the growth() function to calculate NPP for each LAI value
source
Biome.fire — Function

fire(wet::AbstractVector{T}, pft::U, lai::T, npp::T)::AbstractPFT

Calculate the number of potential fire days in a year based on threshold values for soil moisture.

Arguments

  • wet: A vector of 365 T values representing daily wetness.
  • pft: An integer representing the Plant Functional Type (PFT).
  • lai: The Leaf Area Index.
  • npp: Net Primary Productivity.

Returns

  • 'pft`: An updated Plant Functional Type (PFT) with the number of fire days set.'
source
Biome.growth — Function
growth(maxlai, annp, sun, temp, dprec, dmelt, dpet, k, pft, dayl, dtemp, dphen, co2, p, tsoil, mnpp, c4mnpp)

Calculate net primary productivity and carbon fluxes for a plant functional type. This is the main growth function that integrates photosynthesis, respiration, hydrology, and carbon cycling to determine NPP and related carbon fluxes. The function handles both C3 and C4 photosynthesis pathways and includes iterative optimization for photosynthesis-conductance coupling.

Arguments

  • maxlai: Maximum leaf area index
  • annp: Annual precipitation (mm)
  • sun: Monthly solar radiation (12 elements, MJ/m²/day)
  • temp: Monthly temperature (12 elements, °C)
  • dprec: Daily precipitation (365 elements, mm)
  • dmelt: Daily snowmelt (365 elements, mm)
  • dpet: Daily potential evapotranspiration (365 elements, mm)
  • k: Soil and canopy parameter array
  • pft: Plant functional type
  • dayl: Monthly day length (12 elements, hours)
  • dtemp: Daily temperature (365 elements, °C)
  • dphen: Daily phenology array (365x2 matrix)
  • co2: Atmospheric CO2 concentration (ppm)
  • p: Atmospheric pressure (kPa)
  • tsoil: Monthly soil temperature (12 elements, °C)
  • mnpp: Monthly NPP array to be filled (12 elements)
  • c4mnpp: Monthly C4 NPP array to be filled (12 elements)

Returns

A tuple containing:

  • npp: Annual net primary productivity (gC/m²/year)
  • mnpp: Monthly NPP values (12 elements, gC/m²/month)
  • c4mnpp: Monthly C4 NPP values (12 elements, gC/m²/month)

Notes

  • Includes iterative bisection method for photosynthesis-conductance coupling
  • Handles mixed C3/C4 photosynthesis for certain PFTs
  • Integrates fire disturbance effects
  • Calculates isotopic signatures for carbon cycling
source
Biome.hetresp — Function
hetresp(pft, nppann, tair, tsoil, aet, moist, isoveg, Rlit, Rfst, Rslo, Rtot, isoR, isoflux, Rmean, meanKlit, meanKsoil)

Model heterotrophic respiration of litter and soil organic carbon in both a fast and a slow pool. It assumes equilibrium and so decays all of a given year's NPP. The 13C composition of respired CO2 is also modeled.

Arguments

  • pft: Plant Functional Type.
  • nppann: Annual Net Primary Productivity.
  • tair: Array of monthly air temperatures.
  • tsoil: Array of monthly soil temperatures.
  • aet: Array of monthly Actual Evapotranspiration values.
  • moist: Array of monthly soil moisture values.
  • isoveg: 13C composition of vegetation.
  • Rlit: Vector for litter respiration values (modified in place).
  • Rfst: Vector for fast pool respiration values (modified in place).
  • Rslo: Vector for slow pool respiration values (modified in place).
  • Rtot: Vector for total respiration values (modified in place).
  • isoR: Vector for isotope respiration values (modified in place).
  • isoflux: Vector for isotope flux values (modified in place).
  • Rmean: Mean respiration value.
  • meanKlit: Mean litter decay constant.
  • meanKsoil: Mean soil decay constant.

Returns

A tuple containing:

  • Rlit: Monthly litter respiration rates (Vector{T}).
  • Rfst: Monthly fast pool respiration rates (Vector{T}).
  • Rslo: Monthly slow pool respiration rates (Vector{T}).
  • Rtot: Monthly total respiration rates (Vector{T}).
  • isoR: Monthly isotope respiration values (Vector{T}).
  • isoflux: Monthly isotope flux values (Vector{T}).
  • Rmean: Mean annual respiration rate (T).
  • meanKlit: Mean litter decay constant (T).
  • meanKsoil: Mean soil decay constant (T).
source
Biome.hydrology — Function
hydrology(dprec, dmelt, deq, root, k, maxfvc, pft, phentype, wst, gcopt, mgmin, dphen, dtemp, sapwood, emax) :: HydrologyResults

Calculate the actual values of canopy conductance (gc), soil moisture, and other hydrological variables.

Arguments:

  • dprec: Daily precipitation (365-element vector).
  • dmelt: Daily snowmelt (365-element vector).
  • deq: Daily equilibrium evapotranspiration (365-element vector).
  • root: Root fraction (scalar).
  • k: Array of soil and canopy parameters (vector of 7 elements).
  • maxfvc: Maximum foliar vegetation cover (scalar).
  • pft: Plant Functional Type (scalar).
  • phentype: Phenological type (scalar).
  • wst: Initial soil moisture (scalar).
  • gcopt: Optimal canopy conductance (365-element vector).
  • mgmin: Minimum canopy conductance modifier (scalar).
  • dphen: Phenology data (365x2 matrix).
  • dtemp: Daily temperature (365-element vector).
  • sapwood: Presence of sapwood respiration.
  • emax: Maximum evapotranspiration efficiency (scalar).

Returns:

  • meanfvc: Mean monthly foliar vegetation cover.
  • meangc: Mean monthly canopy conductance.
  • meanwr: Mean monthly soil water reservoir (root zone, layer 1, and layer 2).
  • meanaet: Mean monthly actual evapotranspiration.
  • runoffmonth: Monthly runoff values.
  • wet: Daily soil water reservoir values.
  • dayfvc: Daily foliar vegetation cover.
  • annaet: Annual actual evapotranspiration.
  • sumoff: Total runoff and drainage.
  • greendays: Number of days with active vegetation.
  • runnoff: Final runoff value.
  • wilt: Boolean indicating whether wilting occurred.
source
Biome.isotope — Function
isotope(Cratio, Ca, temp, Rd, c4month, mgpp, phi, gpp)

Calculate the total fractionation of 13C as it goes from free air (as 13CO2) to fixed carbon in the leaf. For use with the BIOME3 model of A. Haxeltine (1996). There are separate routines for calculating fractionation by both C3 and C4 plants. This program is based upon the model used by Lloyd and Farquhar (1994).

Arguments

  • Cratio: Monthly ratios of intercellular to ambient CO2 concentration.
  • Ca: Ambient CO2 concentration (ppm).
  • temp: Monthly air temperatures (°C).
  • Rd: Monthly daytime respiration rates (µmol m⁻² s⁻¹).
  • c4month: Boolean vector indicating C4 photosynthesis months.
  • mgpp: Monthly gross primary productivity values.
  • phi: Maximum quantum yield of photosynthesis.
  • gpp: Annual gross primary productivity.

Returns

A tuple containing:

  • meanC3: Mean C3 isotopic fractionation weighted by GPP.
  • meanC4: Mean C4 isotopic fractionation weighted by GPP.
  • C3DA: Monthly C3 isotopic fractionation values.
  • C4DA: Monthly C4 isotopic fractionation values.
source
Biome.phenology — Function
phenology(dphen, dtemp, temp, tcm, tmin, pft, ddayl)

Calculate a generic phenology for any summergreen plant functional type.

A three month period centered around the coldest month is defined as the minimum period during which foliage is not present. Plants then start growing leaves at the end of this 3 month period or when the temperature goes above 5°C if this occurs later. Plants take 200 Growing Degree Days at 5°C (GDD5) to grow a full leaf canopy.

Arguments

  • dphen: Daily phenology array (365x2 matrix) to be modified
  • dtemp: Daily temperature array (365 elements, °C)
  • temp: Monthly temperature array (12 elements, °C)
  • tcm: Temperature of the coldest month (°C)
  • tmin: Minimum temperature (°C)
  • pft: Plant Functional Type
  • ddayl: Daily day length array (365 elements, hours)

Returns

  • dphen: Modified daily phenology array (365x2 matrix)

Notes

  • Phencase 1: Evergreen Phenology
  • Phencase 2: Alternative phenology based on GDD0
  • Fall leaf drop occurs when temperature < -10°C or day length < 10 hours
source
Biome.photosynthesis — Function
photosynthesis(ratio, dsun, daytime, temp, age, fpar, p, ca, pft)

Calculate C3 photosynthesis based on environmental and plant functional type (PFT) parameters.

Arguments

  • ratio: The ratio of intercellular to ambient CO2 concentration.
  • dsun: Daily solar radiation (MJ/m²/day).
  • daytime: Length of the day (hours).
  • temp: Air temperature (°C).
  • age: Leaf age (months).
  • fpar: Fraction of photosynthetically active radiation absorbed by the canopy.
  • p: Atmospheric pressure (kPa).
  • ca: Ambient CO2 concentration (ppm).
  • pft: Plant Functional Type (integer index).

Returns

  • leafresp: Leaf respiration rate.
  • grossphot: Gross photosynthesis rate.
  • aday: Net daily photosynthesis.
source
Biome.ppeett — Function
ppeett(lat, dtemp, dclou, temp, env=nothing)

Calculate insolation and potential evapotranspiration (PET) for each month.

This function computes daily potential evapotranspiration, day length, solar radiation, and annual radiation based on latitude, temperature, and cloud cover. If environment data is provided, it will be used to override the calculated values.

Arguments

  • lat: Latitude in degrees
  • dtemp: Daily temperature array (365 elements, °C)
  • dclou: Daily cloud cover array (365 elements, %)
  • temp: Monthly temperature array (12 elements, °C)
  • env: Optional NamedTuple with pre-calculated values (:dpet, :dayl, :sun, :rad0, :ddayl)

Returns

A tuple containing:

  • dpet: Daily potential evapotranspiration (365 elements, mm/day)
  • dayl: Monthly day length (12 elements, hours)
  • sun: Monthly solar radiation (12 elements, MJ/m²/day)
  • rad0: Annual radiation sum (MJ/m²/year)
  • ddayl: Daily day length (365 elements, hours)

Notes

  • If env data is provided, those values take precedence over calculated ones
source
Biome.respiration — Function
respiration(gpp, alresp, temp, sapwood, lai, monthlyfpar, pft)

Calculate plant respiration components and net primary productivity (NPP) from gross primary productivity (GPP).

This function computes various respiration costs including stem maintenance, belowground maintenance, leaf respiration, and growth respiration to determine the net primary productivity of a plant functional type.

Arguments

  • gpp: Gross primary productivity (carbon gained through photosynthesis)
  • alresp: Autotrophic leaf respiration
  • temp: Monthly temperature array (12 elements)
  • sapwood: sapwood indicator (2 = sapwood, other = woody)
  • lai: Leaf area index
  • monthlyfpar: Monthly fraction of photosynthetically active radiation (12 elements)
  • pft: Plant functional type identifier

Returns

A tuple containing:

  • npp: Net primary productivity (-9999.0 if below minimum allocation requirement)
  • stemresp: Total annual stem maintenance respiration
  • percentcost: Respiration costs as percentage of GPP
  • mstemresp: Monthly stem maintenance respiration (12 elements)
  • mrootresp: Monthly root maintenance respiration (12 elements)
  • backleafresp: Monthly leaf maintenance respiration (12 elements)

Notes

  • For sapwood PFTs (sapwood == 2), stem respiration is set to zero
  • Temperature-dependent respiration follows exponential relationship with reference temperature of 10°C
  • NPP is set to -9999.0 if it falls below the minimum allocation requirement
  • Function uses multiple hardcoded constants that should ideally be moved to a constants module
source
Biome.snow — Function
snow(dtemp, dprecin)

Calculate daily precipitation and snowmelt from daily temperature and precipitation input. Snow accumulates when temperature is below the snow threshold and melts when temperature is above it.

Arguments

  • dtemp: Daily temperature array (365 elements, °C)
  • dprecin: Daily precipitation input array (365 elements, mm)

Returns

A tuple containing:

  • dprec: Daily precipitation (rain) after accounting for snow (365 elements)
  • dmelt: Daily snowmelt (365 elements, mm)
  • maxdepth: Maximum snow depth reached during the year (mm)

Notes

  • Snow threshold temperature is set to -1.0°C
  • Melt coefficient is 0.7 mm/°C/day
  • Function runs twice to ensure equilibrium
source
Biome.table — Function
table(tc)

Extract Gamma and Lambda based on temperature.

Looks up gamma and lambda from the table based on the given temperature (tc).

Author: Wolfgang Cramer, Dept. of Geography, Trondheim University-AVH, N-7055 Dragvoll, Norway. Latest revisions 14/2-1991

Arguments

  • tc: Temperature for which gamma and lambda are looked up.

Returns

  • Tuple{T, T}: gamma and lambda values based on the provided temperature.
source

BIOME4-specific functions

Biome.BIOME4.assign_biome — Function
assign_biome(optpft::LichenForb, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for LichenForb plant functional type.

Returns Barren biome as LichenForb typically occurs in harsh environments.

source
assign_biome(optpft::TundraShrubs, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for TundraShrubs plant functional type.

Uses growing degree days above 0°C to determine tundra biome type.

source
assign_biome(optpft::ColdHerbaceous, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for ColdHerbaceous plant functional type.

Returns SteppeTundra biome for cold herbaceous vegetation.

source
assign_biome(optpft::BorealEvergreen, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for BorealEvergreen plant functional type.

Uses GDD5 and coldest month temperature to determine forest type.

source
assign_biome(optpft::BorealDeciduous, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for BorealDeciduous plant functional type.

Determines forest type based on subordinate PFT and climate conditions.

source
assign_biome(optpft::WoodyDesert, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for WoodyDesert plant functional type.

Uses NPP and LAI to determine desert or shrubland biome type.

source
assign_biome(optpft::C3C4TemperateGrass, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for C3C4TemperateGrass plant functional type.

Uses NPP and GDD0 to determine grassland or tundra biome type.

source
assign_biome(optpft::TemperateBroadleavedEvergreen, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for TemperateBroadleavedEvergreen plant functional type.

Uses NPP to determine if mixed forest or desert biome is appropriate.

source
assign_biome(optpft::TemperateDeciduous, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for TemperateDeciduous plant functional type.

Complex logic considering co-occurring PFTs and climate conditions.

source
assign_biome(optpft::CoolConifer, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for CoolConifer plant functional type.

Determines conifer forest type based on co-occurring PFTs.

source
assign_biome(optpft::TropicalEvergreen, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for TropicalEvergreen plant functional type.

Returns tropical evergreen forest if NPP is sufficient, otherwise desert.

source
assign_biome(optpft::TropicalDroughtDeciduous, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for TropicalDroughtDeciduous plant functional type.

Uses NPP and green days to determine tropical forest type.

source
assign_biome(optpft::C4TropicalGrass, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for C4TropicalGrass plant functional type.

Returns tropical grassland if NPP is sufficient, otherwise desert.

source
assign_biome(optpft::Default, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for Default plant functional type.

Uses woody dominant PFT to determine appropriate biome type.

source
assign_biome(optpft::None, subpft, wdom, gdd0, gdd5, tcm, tmin, pftlist)

Assign biome for None plant functional type.

Returns Barren biome when no vegetation is present.

source