Imported from lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation (models/LPJ_GUESS/SKILL.md). Install upstream with npx skills add lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation --skill LPJ_GUESS. Copyright stays with the author.

MANDATORY EXECUTION POLICY — READ BEFORE PROCEEDING

You MUST run the actual model binary or package described in this document. If the model fails to import, compile, or execute, you MUST:

1. Check diagnostics/triplets.yaml for a matching error pattern
2. Try the fix suggested in the triplet's remedy section
3. If still failing, report the error to the user with full details

You MUST NOT substitute a simplified Python formula, regression equation, or hand-coded approximation in place of the real model.

Before starting, run: python preflight_check.py (in this KI directory) to verify that the model binary/package and required data are available.

DEBUGGING PROTOCOL — When something goes wrong, follow this order:

1. Check triplets — diagnostics/triplets.yaml may already cover this error
2. Read official docs — The model's own documentation for expected formats/units
3. Find working examples — Check outputs/ or the model's shipped test data
4. Fix the tool — With knowledge of what "correct" looks like

Do NOT write custom debug scripts. The answers are in the docs and examples.

KI map — what to read, and when

Projected 2026-08-17 from the KI's actual contents — 9 components present. Refresh: python3 ki_tools_common/generate_skill_map.py --ki_dir <this KI>.

Executable tool index (projected — complete by construction)

Every public tool in this KI, by exact path. What each is FOR lives in the human-written Tool Inventory above; --help on any of these prints its arguments.

4 public tools; _-prefixed helpers and packaging files excluded.

LPJ-GUESS (Lund-Potsdam-Jena General Ecosystem Simulator) -- Knowledge Infrastructure

Package: kdt-lpj-guess v1.0.0 Model: LPJ-GUESS (dynamic vegetation / biogeochemistry model) Domain: Terrestrial biogeochemistry (C/N cycling, vegetation dynamics) Created by: KDT Auto-Dissection Last updated: 2026-03-30 Stats: 4 tools | 1 skill document | ~2,400 lines of validated Python Validation status: analytic (reimplemented physics validated against FLUXNET2015 eddy-covariance)

Data Preparation

Forcing data

Data Sources: Use from ki_tools_common.load_forcing import load_daily_forcing for CMFD/MSWX/NASA POWER.

Data Validation Reference: See data_ki/CMFD/SKILL.md for CMFD unit documentation and known traps. See data_ki/FLUXNET/SKILL.md for eddy covariance flux observations.

Overview

This knowledge infrastructure enables autonomous simulation of terrestrial ecosystem carbon and nitrogen cycling using the core physics of LPJ-GUESS. The pipeline converts FLUXNET2015 or gridded reanalysis forcing data to LPJ-GUESS input format, manages PFT and site parameters, runs the analytic reimplementation of core processes, and parses output timeseries of GPP, NEE, and ecosystem respiration.

What LPJ-GUESS does: Dynamic global vegetation model simulating:

• Carbon assimilation: Light Use Efficiency (LUE) model for GPP (Monteith 1972 approach) with parabolic temperature response and exponential VPD limitation
• Autotrophic respiration: maintenance respiration via Q10 temperature dependence, growth respiration as a fixed fraction of NPP
• Heterotrophic respiration: temperature- and moisture-dependent decomposition of litter and soil organic carbon pools (Q10 formulation)
• Carbon/Nitrogen cycling: coupled C/N dynamics with N limitation on productivity, N mineralization, and N deposition inputs
• Vegetation dynamics: establishment, mortality, competition among Plant Functional Types (PFTs) based on bioclimatic limits and resource availability
• Water stress: stomatal closure under high VPD reduces GPP via a VPD scalar
• NEE computation: NEE = Reco - GPP (ecosystem sign convention: negative = carbon sink)

Key model characteristics:

• Patch-based (cohort mode) or population-based (area-averaged) vegetation representation
• Daily timestep for carbon/water, annual timestep for vegetation dynamics
• Multiple PFTs compete for light and water within each patch
• Stochastic disturbance (fire, windthrow)
• Supports both site-level and gridded simulations

Core Physics

1. GPP via Light Use Efficiency (LUE)

LPJ-GUESS computes Gross Primary Production using a radiation-driven LUE approach:

PAR = SW_IN * 0.48                  # Photosynthetically Active Radiation (W/m2)
PAR_MJ = PAR * 86400 / 1e6          # Convert to MJ/m2/day

f_T = parabolic(T, T_min, T_opt, T_max)   # Temperature scalar [0, 1]
f_VPD = exp(-ln(2) * max(VPD - VPD_0, 0) / VPD_1)  # VPD scalar [0.05, 1]

GPP_gC = LUE_max * PAR_MJ * f_T * f_VPD   # gC/m2/day
GPP_umol = GPP_gC * 1e6 / 12.011 / 86400  # umol CO2/m2/s

Parameters:

• LUE_max: Maximum light use efficiency (typical 1.0-3.0 gC/MJ PAR)
• T_opt: Optimal temperature for photosynthesis (default 20 C)
• T_min / T_max: Min/max temperature limits (default -2 / 38 C)
• VPD_0: VPD threshold before GPP decline (default 10 hPa)
• VPD_1: VPD at which GPP halves (default 35 hPa)
• SW_in_scale: Fraction of shortwave that is PAR (0.48)

2. Autotrophic Respiration (Ra)

Maintenance respiration follows a Q10 temperature response:

f_T = Q10_Ra ^ ((T - T_ref) / 10)
Ra = Ra_base * GPP * f_T / Q10_Ra    # Normalized at T_ref

Parameters:

• Ra_base: Base fraction of GPP allocated to respiration (default 0.5)
• Ra_Q10: Q10 coefficient for maintenance respiration (default 2.0)
• Ra_Tref: Reference temperature (default 15 C)

Growth respiration is implicitly included as a fixed fraction (NPP = GPP - Ra).

3. Heterotrophic Respiration (Rh)

Decomposition of soil/litter carbon pools follows Q10 kinetics:

f_T = Q10_Rh ^ ((T - T_ref) / 10)
Rh = Rh_base * f_T * C_pool_scale

Parameters:

• Rh_base: Base heterotrophic respiration rate (default 2.0 umol/m2/s)
• Rh_Q10: Q10 for decomposition (default 2.0)
• Rh_Tref: Reference temperature (default 15 C)
• C_pool_scale: Scaling factor for soil C pool effect (default 1.0)

4. Net Ecosystem Exchange (NEE)

Reco = Ra + Rh
NEE  = Reco - GPP    # Positive = net source, Negative = net sink

Required Inputs

Meteorological Forcing

Supported forcing sources:

• FLUXNET2015 FULLSET (daily DD or monthly MM CSV files)
• CMFD (China Meteorological Forcing Dataset): temperature in K, precip in kg/m2/s
• MSWX (Multi-Source Weather): temperature in K, precip in mm/3hr

CRITICAL UNIT TRAPS

• Temperature: CMFD/MSWX provide K; LPJ-GUESS expects deg C. Subtract 273.15.
• Precipitation: CMFD provides kg/m2/s; must multiply by 86400 for mm/day. MSWX provides mm/3hr; sum 8 steps per day.
• VPD: FLUXNET provides hPa; some datasets provide kPa (multiply by 10) or Pa (divide by 100).
• SW radiation: Must be total incoming shortwave, not net radiation.
• Missing values: FLUXNET uses -9999 as fill value. Must be converted to NaN before processing.

Unit Conversion Table

This table restates the unit conversions documented by this KI body and its source data notes. Exact I/O shapes live in docs/format_spec.yaml; if a generated spec and this prose ever disagree, regenerate this body from the KI sources.

Output Unit Table

This table restates dag.yaml for the observable outputs. The dag is authoritative for output identity; if this section and dag.yaml diverge, dag.yaml wins.

Site/PFT Parameters

Model Outputs

Tool Pipeline

FLUXNET2015 / CMFD / MSWX           Site/PFT parameters
       |                                    |
       v                                    v
convert_forcing_to_lpjguess.py    convert_parameters_to_lpjguess.py
       |                                    |
       +------------------------------------+
       |
       v
run_lpjguess.py  (execution wrapper: loads forcing + params, runs model)
       |
       v
parse_output_lpjguess.py  (extracts GPP, NEE, RECO timeseries to CSV)

Tool inventory

Stage skill documents

• Stage 1: Preflight
• Stage 2: Convert Forcing
• Stage 3: Convert Parameters
• Stage 4: Run LPJ-GUESS Analytic Model
• Stage 5: Parse Output

Validation

Validation uses FLUXNET2015 eddy-covariance tower observations. The pipeline:

1. Loads gap-filled meteorological forcing (SW_IN, TA, VPD) from a FLUXNET site
2. Splits data into calibration (70% of years) and validation (30%) periods
3. Calibrates 6 key parameters using differential evolution optimization
4. Evaluates on held-out validation period
5. Reports R, RMSE, bias, NSE, KGE for GPP and NEE

Preferred validation sites (in priority order): US-Ha1, DE-Tha, US-MMS, FI-Hyy, FR-Pue, IT-Col, US-UMB, BE-Vie, DE-Hai, US-WCr

Validated Results

Validation Campaign Status

The KI body records the FLUXNET2015 validation workflow, preferred tower sites, calibration/validation split, optimization approach, and reported metric names. No completed body-level validation campaign table with achieved calibration, validation, or full-period metric values is recorded here yet; campaign results are pending.

Headline Output

The dag's rank-1 output is:

GPP -- Gross Primary Production (terrestrial vegetation carbon assimilation flux). (umol/m2/s)

Other dag outputs are Ra, Rh, Reco, NEE, and NPP.

Performance Metrics -- Field Convention Bars

These bars restate docs/validation_convention.yaml. The convention is authoritative for metric, direction, pass-bands, and citation keys; null bands are written as "no cited threshold" rather than guessed.

Data Replacement Tracking

References

• Smith, B. et al. (2001). Representation of vegetation dynamics in the modelling of terrestrial ecosystems: comparing two contrasting approaches within European climate space. Global Ecology & Biogeography, 10, 621-637.
• Smith, B. et al. (2014). Implications of incorporating N cycling and N limitations on primary production in an individual-based dynamic vegetation model. Biogeosciences, 11, 2027-2054.
• Monteith, J.L. (1972). Solar radiation and productivity in tropical ecosystems. J. Applied Ecology, 9, 747-766.
• Sitch, S. et al. (2003). Evaluation of ecosystem dynamics, plant geography and terrestrial carbon cycling in the LPJ dynamic global vegetation model. Global Change Biology, 9, 161-185.