CLM5___CTSM · diff

git:20260817.960ae14 to git:20260817.6859167

11 added, 0 removed. Audit C to A.

+ ---

+ name: clm5-ctsm

+ description: >-

+ CLM5/CTSM (CTSM 5.4 framework; CLM4.5/CLM5.0/CLM6.0 selectable physics). Covers

+ Terrestrial biogeophysics: surface radiation, surface energy balance, canopy and ground

+ turbulent…; Soil and snow thermal dynamics (25 soil layers to ~8.5 m; up to 12 snow

+ layers); Soil and snow hydrology: infiltration, soil moisture, surface/subsurface

+ runoff, drainage. Use when the task involves running, configuring, calibrating or

+ interpreting CLM5___CTSM.

+ ---

> **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.

# CLM5 / CTSM Knowledge Infrastructure

- **Package**: CLM5___CTSM Knowledge Infrastructure v1.0

- **Model**: Community Land Model 5 / Community Terrestrial Systems Model (CTSM 5.4)

- **Domain**: Biogeochemistry, Land Surface, Hydrology, Carbon-Nitrogen Cycling

- **Created**: 2026-03-26

- **Tools**: 4 Python scripts

- **Validation**: Documented

---

## Data Preparation

### Forcing data

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

For a FLUXNET tower site, drive the model with the tower's own meteorology via

`convert_forcing_to_clm.py --source fluxnet` (see §15).

**Data Validation Reference**: `data_ki/CMFD/SKILL.md` and `data_ki/FLUXNET/SKILL.md`

**DO NOT EXIST** — KDT 5.0 removed tools and docs from `data_ki/`. The live

sources are `ki_tools_common` (`KISSPATH_KI_TOOLS_COMMON/`)

and this KI's own `tools/`. FLUXNET2015 layout: one directory per site under

`KISSPATH_OBS/fluxnet/sites/<SITE_ID>/`, holding

`FULLSET_{HH|HR}.csv` (sub-daily), `FULLSET_DD.csv` (daily), `FULLSET_YY.csv`,

`AUXMETEO.csv`, `AUXNEE.csv`. Site coordinates / IGBP class / canopy height are

NOT in `site_catalog.csv` — they are in the BIF workbook

`raw_zips/FLX_AA-Flx_BIF_ALL_20200501.zip` (`LOCATION_LAT`, `LOCATION_LONG`,

`LOCATION_ELEV`, `IGBP`, `HEIGHTC` rows, per `SITE_ID`).

## 1. Overview

This knowledge infrastructure enables an AI agent to configure, execute, and

analyse the Community Land Model version 5 (CLM5), the land component of the

Community Earth System Model (CESM). CLM5 is maintained as part of the

Community Terrestrial Systems Model (CTSM) repository.

**What CLM5 / CTSM does:**

- Simulates terrestrial biogeophysics: radiation transfer, surface energy

balance, soil temperature, and hydrology

- Models biogeochemistry: carbon and nitrogen cycling through vegetation,

litter, and soil organic matter pools

- Represents vegetation dynamics including phenology (CN/BGC modes) and

ecosystem demography (FATES mode)

- Simulates crop growth with prognostic crop calendars and management

(irrigation, fertilisation, harvest) in CLM-Crop mode

- Calculates methane emissions from wetlands (ch4Mod)

- Represents fire effects on ecosystems (CNFireBaseMod)

- Provides urban climate modelling with the CLMU urban canyon model

- Couples to atmosphere via NUOPC or LILAC frameworks and to river

routing via MOSART/mizuRoute

- Supports dynamic land-use and land-cover change via transient PFT

datasets

- Performs nitrogen fixation and uptake via the FUN model

**Key difference from simpler land models:** CLM5 is a full-complexity Earth

System land model with 78+ PFT/CFT types, 25 soil layers to 8.5 m depth,

up to 12 snow layers, and integrated biogeochemistry. It requires CIME

infrastructure and parallel computing resources (MPI + NetCDF + ESMF).

---

## 2. Installation

### Binary / Source

CLM5 is compiled from Fortran source using the CIME build system. There is no

standalone binary distribution.

```

Source root: source/repo/

CTSM version: 5.4

Primary language: Fortran 2003+

Build system: CIME (CMake under the hood, CMake 3.10+)

```

### System Dependencies

| Dependency | Purpose | Required |

|---|---|---|

| Fortran compiler (gfortran/ifort/nvfortran) | Compile CLM5 source | Yes |

| C compiler (gcc/icc) | Shared code, CIME | Yes |

| MPI (OpenMPI/MPICH/Intel MPI) | Parallel execution | Yes |

| NetCDF-Fortran >= 4.7.4 | I/O for all data files | Yes |

| ESMF (Earth System Modeling Framework) | Coupling infrastructure | Yes |

| PIO (Parallel I/O) | Efficient parallel NetCDF | Yes |

| Python >= 3.8 | CIME scripts, tools | Yes |

| CMake >= 3.10 | Build system | Yes |

| LAPACK/BLAS | Linear algebra | Optional |

| pFUnit | Fortran unit testing | Optional |

### Python Dependencies (for tools)

```

numpy

pandas

xarray

netCDF4

matplotlib

pyyaml

```

### Typical CIME Workflow

```bash

# 1. Set environment

export CTSMROOT=/path/to/ctsm

export CIMEROOT=$CTSMROOT/cime

# 2. Create a new case

cd $CIMEROOT/scripts

./create_newcase --case /path/to/cases/test_I2000 \

--res f09_g17 --compset I2000Clm60BgcCrop

# 3. Setup, build, submit

cd /path/to/cases/test_I2000

./case.setup

./case.build

./case.submit

```

---

## 3. Pipeline

|---|---|---|---|

**Parallelism:** Stages 1-4 can run in parallel. Stage 5 depends on 1-4.

Stage 6 depends on 5. Stages 7-10 depend on 6.

---

## 4. Tools Reference

|---|---|---|---|

| make_site_dataset.py | s1+s4 | ki/tools/make_site_dataset.py | Single-point surfdata + domain + site aerosol stream file (replaces mksurfdata_esmf / ESMF_RegridWeightGen, which need an ESMF-with-PIO build — see dt_022) |

| convert_forcing_to_clm.py | s2 | ki/tools/convert_forcing_to_clm.py | Convert GSWP3/CRUJRA/ERA5/CSV/**FLUXNET** to DATM format; `--datm-layout clm1pt` writes the monthly `YYYY-MM.nc` layout DATM actually reads |

**`run_clm.py --action configure`** is the only KI route to `./xmlchange` and

`user_nl_*`. Editing `env_*.xml` by hand bypasses CIME's LockedFiles check:

```bash

python tools/run_clm.py --action configure --case-dir $CASE \

--xmlchange STOP_N=1 --xmlchange CONTINUE_RUN=TRUE \

--append-user-nl "clm:/path/to/user_nl_clm_fragment.txt"

```

---

## 5. Skill Knowledge

| Stage | Topic | Document |

|---|---|---|

| s0 | Configuration and compsets | docs/s0_configuration_skill.md |

| s2 | Atmospheric forcing preparation | docs/s2_forcing_skill.md |

| s3 | Soil parameter preparation | docs/s3_soil_params_skill.md |

| s6 | Model execution | docs/s6_execution_skill.md |

| s7 | Output analysis | docs/s7_output_analysis_skill.md |

---

## 6. Critical Domain Knowledge

### dt_001: Precipitation units — mm/s vs mm/day vs kg/m2/s

CLM5 DATM expects precipitation in **kg/m2/s** (equivalent to mm/s). Many

reanalysis products provide mm/day or mm/3hr. Failing to divide by 86400

(or 10800 for 3-hourly) produces runoff that is 86400x too large, typically

crashing the model or producing NaN soil moisture.

**Root cause:** No automatic unit detection in DATM streams.

**Silent failure mode:** If forcing values are merely 10x wrong (e.g.,

mm/hr used as mm/s), CLM may run but produce unrealistic runoff.

### dt_002: Temperature in Celsius vs Kelvin

CLM5 expects atmospheric temperature in **Kelvin**. Providing Celsius

causes near-zero longwave radiation, freezing soils even in summer, and

incorrect saturation vapor pressure. The model will run but produce

physically meaningless energy fluxes.

**Root cause:** No bounds checking on input temperature.

### dt_003: Longwave radiation sign and units

CLM5 expects downward longwave radiation in **W/m2** (positive downward).

Some products provide net longwave or upward longwave. Using net longwave

causes energy imbalance and rapid soil cooling.

### dt_004: Specific humidity vs relative humidity

CLM5 DATM expects **specific humidity (kg/kg)**. Providing relative humidity

(0-100 or 0-1 fraction) causes latent heat flux errors. RH of 80% entered

as 80.0 kg/kg would cause immediate model failure; RH of 0.8 entered as

specific humidity produces severe drying.

### dt_005: Soil layer mismatch — 25 layers to 8.5 m

CLM5 uses 25 soil layers with exponentially increasing thickness from 1.75 cm

(layer 1) to 1.136 m (layer 25), reaching 8.5 m total depth. External soil

data (typically 6 layers to 2 m in HWSD) must be interpolated carefully.

Using constant-depth interpolation misrepresents deep soil properties.

### dt_006: PFT fraction normalization

The surface dataset requires PFT fractions to sum to exactly 1.0 per grid

cell (after accounting for lake, wetland, glacier, and urban fractions).

Fractions summing to > 1.0 cause mass conservation violations; fractions

< 1.0 leave "bare ground" that may behave unexpectedly.

### dt_007: Calendar mismatch (noleap vs gregorian)

CLM5 typically runs with a **noleap** (365-day) calendar. If forcing data

uses a gregorian calendar with leap years, Feb 29 data causes date

misalignment that accumulates over decades. The model may crash at the

calendar boundary or silently use wrong forcing.

### dt_008: CO2 concentration units — ppmv

CLM5 expects CO2 in **ppmv** (parts per million by volume). The namelist

variable `co2_ppmv` defaults to ~367 ppmv for year 2000. Providing

concentration in mol/mol (3.67e-4) or ug/m3 produces near-zero

photosynthesis (GPP).

### dt_009: Spinup requirements — decades to centuries

CLM5 BGC mode requires 200-600+ years of spinup to equilibrate soil

carbon pools. Running without adequate spinup produces transient carbon

fluxes that do not represent the actual ecosystem. Accelerated decomposition

(CLM_ACCELERATED_SPINUP=on) reduces this to ~50-100 years but must be

followed by a normal-mode "exit spinup" run.

---

## 7. Validation

### Test Configuration

- **Mode**: Single-point (1PT) with GSWP3 forcing

- **Physics**: CLM6.0 BGC

- **Compset**: I2000Clm60BgcCrop

- **Resolution**: f09_g17 (0.9x1.25 degree) or single-point

- **Period**: 2000-2010

### Key Output Variables

| Variable | Long Name | Units |

|---|---|---|

| GPP | Gross Primary Production | gC/m2/s |

| NPP | Net Primary Production | gC/m2/s |

| NEE | Net Ecosystem Exchange | gC/m2/s |

| EFLX_LH_TOT | Total Latent Heat Flux | W/m2 |

| FSH | Sensible Heat Flux | W/m2 |

| QRUNOFF | Total Runoff | mm/s |

| H2OSOI | Soil Moisture by Layer | mm3/mm3 |

| TSOI | Soil Temperature by Layer | K |

| TOTSOMC | Total Soil Organic Carbon | gC/m2 |

| TOTVEGC | Total Vegetation Carbon | gC/m2 |

| SNOW_DEPTH | Snow Depth | m |

| FSNO | Fraction of Ground Covered by Snow | fraction |

### Published Reference Values (Global Means)

|---|---|---|---|

| GPP | ~120 | PgC/yr | Lawrence et al. 2019 |

| Soil Carbon | ~1500 | PgC | Lawrence et al. 2019 |

| Vegetation Carbon | ~350 | PgC | Lawrence et al. 2019 |

### Key Findings

1. CLM5 produces reasonable global carbon cycle when properly spun up

2. Single-point simulations are most practical for initial validation

3. Forcing data quality is the primary determinant of simulation quality

4. Soil carbon equilibrium requires > 200 years of spinup in BGC mode

---

## 8. Calibration Parameters

|---|---|---|---|---|

---

## 9. Coupling Points

|---|---|---|---|---|

---

## 10. Data Requirements

|---|---|---|---|

---

## 11. Quick Start Examples

### Example 1: Create a single-point case

```bash

cd $CIMEROOT/scripts

./create_newcase --case ~/cases/1pt_test \

--res CLM_USRDAT --compset I2000Clm60Sp \

--run-unsupported

cd ~/cases/1pt_test

./xmlchange CLM_USRDAT_NAME=1x1_brazil

./case.setup

./case.build

./case.submit

```

### Example 2: Convert ERA5 forcing to DATM format

```bash

python ki/tools/convert_forcing_to_clm.py \

--source era5 \

--input /path/to/era5_hourly.nc \

--output /path/to/datm_forcing/ \

--start-year 2000 --end-year 2010

```

### Example 3: Run CLM with pre-built case

```bash

python ki/tools/run_clm.py \

--case-dir /path/to/cases/my_case \

--timeout 7200

```

### Example 4: Parse output to CSV

```bash

python ki/tools/parse_clm_output.py \

--history-dir /path/to/archive/lnd/hist/ \

--variables GPP,QRUNOFF,EFLX_LH_TOT \

--output results.csv

```

### Example 5: Adjust namelist for BGC spinup

```bash

cd /path/to/cases/my_case

./xmlchange CLM_ACCELERATED_SPINUP=on

./xmlchange STOP_OPTION=nyears

./xmlchange STOP_N=100

cat >> user_nl_clm << 'EOF'

hist_nhtfrq = -8760

hist_mfilt = 1

hist_fincl1 = 'TOTSOMC', 'TOTVEGC', 'GPP', 'NEE'

EOF

./case.build

./case.submit

```

---

## 12. Diagnostic Triplets Summary

See `diagnostics/triplets.yaml` for full details.

|---|---|---|---|

**Silent errors:** 6 of 15 triplets (40%) are silent — the model runs but

produces incorrect results. The most critical is dt_001 (precipitation

unit mismatch) which can produce runoff 86400x too high.

---

## 13. File Structure

```

ki/

SKILL.md -- This file

tools/

convert_forcing_to_clm.py -- Stage 2: forcing converter

convert_soil_params.py -- Stage 3: soil parameter mapper

run_clm.py -- Stage 6: execution wrapper

parse_clm_output.py -- Stage 7: output parser

docs/

s0_configuration_skill.md -- Configuration and compsets

s2_forcing_skill.md -- Atmospheric forcing preparation

s3_soil_params_skill.md -- Soil parameter preparation

s6_execution_skill.md -- Model execution

s7_output_analysis_skill.md -- Output analysis and validation

diagnostics/

triplets.yaml -- 15 diagnostic triplets

```

---

## 14b. WHICH CLM INSTALLATION TO USE *(read before anything else)*

`preflight_check.py` pins `KISSPATH_HOME/cesm/scratch/test_clm5/bld/cesm.exe`.

That binary **cannot initialise**: it is a CTSM-5.4 / NUOPC build whose ESMF was

compiled without PIO, so `ESMCI_mesh_create_from_file()` aborts in

`atm_comp_nuopc.F90` a second after launch (dt_022). `mksurfdata_esmf` is dead

for the same reason.

**Use CESM 2.2.2 with the MCT driver instead** — it is fully installed and has a

recorded `model execution success` (case `B1850_test`, 2026-05-02):

| Item | Path |

|---|---|

| CESM root (`--ctsm-root`) | `KISSPATH_HOME/cesm/src/cesm-2.2.2` |

| Machine | `hydrocraft_server` (config in `KISSPATH_HOME/.cime/`) |

| `DIN_LOC_ROOT` | `KISSPATH_HOME/cesm/inputdata` |

| `DIN_LOC_ROOT_CLMFORC` | `KISSPATH_HOME/cesm/inputdata/atm/datm7` |

| Cases / scratch | `KISSPATH_HOME/cesm/cases`, `KISSPATH_HOME/cesm/scratch` |

| Batch system | none — `./case.submit` runs the model synchronously |

Missing inputdata files can be fetched from

`https://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/...` (verified

working). Check `Content-Length` first: the default CESM aerosol-deposition

file is **6.2 GB** (dt_020).

---

## 15. VALIDATED RECIPE — single-point FLUXNET tower run (CLM5-SP)

Executed end to end 2026-08-09 at FLUXNET2015 **US-MMS** (Morgan Monroe State

Forest, 39.3232 N, 86.4131 W, DBF, 1999-2014 hourly). Every step uses a KI tool.

**s1 — site datasets** (surfdata + domain + aerosol, one command):

```bash

python tools/make_site_dataset.py --site-name US-MMS \

--lat 39.3232 --lon -86.4131 --igbp DBF \

--global-surfdata $DIN/lnd/clm2/surfdata_map/release-clm5.0.18/\

surfdata_0.9x1.25_hist_78pfts_CMIP6_simyr1850_c190214.nc \

--outdir $DIN/lnd/clm2/surfdata_map --domain-outdir $DIN/share/domains \

--aerosol-source $DIN/atm/cam/chem/trop_mozart_aero/aero/\

aerosoldep_monthly_2000_mean_1.9x2.5_c090421.nc \

--aerosol-outdir $DIN/atm/cam/chem/trop_mozart_aero/aero --aerosol-year 2000

```

`--igbp` maps the tower's documented vegetation class to a CLM PFT and makes the

cell 100 % that PFT (CTSM `subset_data.py --dompft` behaviour) — this is how a

~100 km parent cell is made to represent a ~1 km tower footprint. LAI/SAI/HTOP

still come from the parent cell's MODIS climatology on the surface dataset. Forcing the cell to one PFT zeroes every non-vegetated landunit, but

`PCT_GLC_MEC` must **still sum to 100 %** across its 10 elevation classes:

`surfrd_special` (surfrdMod.F90:602-607) reads it unconditionally and

`check_sums_equal_1` endruns at surfrdUtilsMod.F90:80 even when

`PCT_GLACIER = 0` (dt_023). `make_site_dataset.py` now writes class 0 = 100

and hard-fails if the sum is not 100.

**s2 — tower meteorology → DATM CLM1PT monthly files**:

```bash

python tools/convert_forcing_to_clm.py --source fluxnet \

--input .../fluxnet/sites/US-MMS/FULLSET_HR.csv \

--output $DIN/atm/datm7/US-MMS/CLM1PT_data --datm-layout clm1pt \

--lat 39.3232 --lon -86.4131 --zbot 46.0 --elevation 275 \

--start-year 1999 --end-year 2014

```

Reads the gap-filled `*_F` columns, converts °C→K, kPa→Pa, mm/step→kg/m²/s,

VPD→**RH in percent** (dt_018), drops Feb 29 for the noleap calendar (dt_007),

stamps each record at the interval MIDPOINT, and resumes by skipping months

already written. `--zbot` must exceed the canopy top on the surface dataset.

**s3-s4 — case**: compset `I1PtClm50SpRsGs`, resolution `CLM_USRDAT`, then

```

CLM_USRDAT_NAME=<site> ATM/LND_DOMAIN_PATH=$DIN/share/domains

ATM/LND_DOMAIN_FILE=domain.lnd.<site>_navy.nc

DATM_CLMNCEP_YR_START/END/ALIGN=1999/2014/1999

DATM_PRESAERO=clim_2000 RUN_STARTDATE=1999-01-01

STOP_OPTION=nyears STOP_N=1 REST_OPTION=nyears REST_N=1

DOUT_S=FALSE CCSM_CO2_PPMV=383.0 CLM_FORCE_COLDSTART=on

```

`user_nl_clm`: `fsurdat` = the site surface dataset, `hist_nhtfrq = -24`,

`hist_mfilt = 365`, and `hist_fincl1` **must request `FPSN`, not `GPP`**

(dt_019). Do **not** also set `finidat` — `finidat` plus

`CLM_FORCE_COLDSTART=on` makes build-namelist exit rc=255.

Then copy `Buildconf/datmconf/datm.streams.txt.presaero.clim_2000` to

`user_datm.streams.txt.presaero.clim_2000` and point it at `aerosoldep_<site>.nc`

(dt_020), re-run `./preview_namelists`, and confirm with `./check_input_data`.

Three small files must be present in inputdata and are NOT shipped:

`atm/datm7/topo_forcing/topodata_0.9x1.25_USGS_070110_stream_c151201.nc` (2 MB),

`atm/cam/chem/trop_mozart/emis/megan21_emis_factors_78pft_c20161108.nc` (67 kB),

and an aerosol-deposition file (use the 9 MB 1.9x2.5 climatology).

**s5 — run**: submit ONE simulated year at a time (`STOP_N=1`, then

`CONTINUE_RUN=TRUE`); the model date is recoverable from `rpointer.lnd`, which

makes a long run resumable after any interruption.

**s6 — score**: `parse_clm_output.py` → `FPSN`, then

`GPP [gC m-2 d-1] = FPSN [umol m-2 s-1] × 12.011e-6 × 86400 = FPSN × 1.03775`,

paired against `GPP_NT_VUT_REF` from `FULLSET_DD.csv` (already gC m-2 d-1).

Discard the first 2 years as soil-moisture/temperature spin-up (SP mode needs no

carbon spin-up, so dt_009 does not apply).

---

## 14. Unit Trap Reference Table

This table summarises every unit conversion required at model boundaries.

|---|---|---|---|---|

| Pressure | ERA5 | Pa | Pa | None (verify 50000-110000) |

| Soil depth | HWSD | cm | m | / 100 |

| Elevation | DEM | m | m | None |