lzwei196/kiss-knowledge-infrastructure-for-scientific-simulation/lpj-guess

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. Doing so produces

scientifically invalid results and defeats the purpose of the KI.

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 (model crashes, wrong output,

unexpected values), follow this order. Do NOT skip steps or write debug scripts:

1. Check triplets — diagnostics/triplets.yaml may already cover this error

2. Read official docs — Check the model's own documentation (PDF manual, README,

official examples) for expected input formats, variable names, and units

3. Find working examples — Look in outputs/ for previous successful runs of

this model, or check if the model ships with test/example data

4. Fix the tool — Now that you know what "correct" looks like, make targeted fixes

Resist the urge to write diagnostic/debug Python scripts. The answers are almost

always in the official docs and working examples, not in reverse-engineering the binary.

<!-- KI-MAP:BEGIN (projected by generate_skill_map.py — edit the KI, not this table) -->

KI map — what to read, and when

Projected 2026-10-07 from the KI's actual contents — 9 components present. Refresh: `python3 ki_tools_common/generate_skill_map.py --ki_dir <this KI>`. <!-- KI-MAP:END -->

<!-- KI-TOOL-INDEX:BEGIN (projected by generate_skill_map.py — the discoverability contract: every public tool, exact path; PURPOSE stays human-authored elsewhere) -->

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.

8 public tools; `_`-prefixed helpers and packaging files excluded. <!-- KI-TOOL-INDEX:END -->

LPJ-GUESS -- Knowledge Infrastructure Skill Document

Version: LPJ-GUESS 4.1.1 (real engine) — KI rewired 2026-10-07

Domain: terrestrial biogeochemistry / dynamic vegetation (C, N, water)

Last updated: 2026-10-07

Validation status: real engine; official demo reproduced exactly (manifest tier tested)

Default run route: tools/run_lpjguess_engine.py (the real guess binary). The surrogate is never the default.

SURROGATE WARNING. tools/run_lpjguess.py, convert_forcing_to_lpjguess.py,

convert_parameters_to_lpjguess.py and parse_output_lpjguess.py are a **Python

light-use-efficiency SURROGATE** (LUE GPP + Q10 respiration) kept for history. They are

not LPJ-GUESS and their numbers must never be reported

as LPJ-GUESS results (dt_lpjguess_033). Their old contract is kept apart in

docs/surrogate_lpjguess_lue_dag.yaml; their old scores sit only under

validation.surrogate_metrics_not_lpjguess in knowledge_infrastructure.yaml. Triplets

dt_lpjguess_001-004 and 011-014 apply to the surrogate only (applies_to: surrogate). Every

result in this document comes from the real engine through the four *_engine* /

build_lpjguess_* tools.

1. Model Identity

2. What This Model Does

LPJ-GUESS simulates vegetation and soil carbon, nitrogen and water from daily weather and CO2. Plants are individuals/cohorts of plant functional types (12 global PFTs in global.ins) that compete for light and water on replicate patches; establishment, mortality and disturbance run yearly. Daily processes: photosynthesis and stomatal conductance (canexch.cpp), multi-layer soil water and snow (soil.cpp), autotrophic respiration; CENTURY soil organic matter with a coupled N cycle (somdynam.cpp, ntransform.cpp); fire (GLOBFIRM here; BLAZE needs files not on the server).

The engine reads climate through input modules: demo (toy monthly climate, used for the official demo), cru (CRU binary archives, not on the server) and cf (CF-NetCDF — what this KI uses for real sites).

Capabilities wired by this KI (full list: docs/input_preparation.md §1):

1. [PRIMARY] Site carbon/water fluxes — GPP, Ra, Rh, Reco, NEE, NPP, ET components, monthly and annual.
2. Official demo / install check — 13 cells, byte-exact against the build-time run.
3. Vegetation composition — PFT selection via --set 'pft "X" ( include 0 )'.
4. Fire model choice — --firemodel GLOBFIRM|NOFIRE|BLAZE.
5. Spin-up / patch / any `.ins` switch — --nyear_spinup, --npatch, --set.
6. Water fluxes — transpiration, soil evaporation, interception, runoff, PET + water-balance check.
7. Scoring against FLUXNET2015 monthly GPP/NEE/RECO/ET.

Not wired yet: crops/land cover/managed forest, transient N deposition, sub-daily output.

3. Input Requirements

Exact shapes: docs/format_spec.yaml (projected from dag.yaml). Preparation plan with the verified shared-library schema: docs/input_preparation.md.

3.1 Meteorological Forcing (CF input, daily)

At least 30 full years are required (spin-up climate = first 30 years; dt_lpjguess_021). Data source used: NASA POWER (global, proxy-safe, ~4 s/yr; shortwave from 1984). FLUXNET met is too short (≤26 yr); CMFD is China-only; MSWX is slow and its 1979 file is broken.

3.2 Static Inputs

3.3 Configuration Files

Copied from src/data/ins/: global.ins (PFTs + switches), global_cf.ins (file paths, imports global.ins and global_soiln.ins), global_demo.ins. The cf mode writes site_cf.ins = global_cf.ins with only the param "file_*" values replaced on active lines, plus appended overrides (later lines win). Nothing is generated from scratch.

4. Build Instructions

Already built — do not rebuild for KI work. For reference (BUILD_LOG.md):

cd KISSPATH_HOME/engine_builds_20261006/LPJ_GUESS/build
cmake ../src -DCMAKE_BUILD_TYPE=Release -DCMAKE_POLICY_VERSION_MINIMUM=3.5
make -j4        # 7 s, warnings only; NetCDF found -> cf input compiled in

5. Execution