Imported from lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation (models/ELM/SKILL.md). Install upstream with npx skills add lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation --skill ELM. 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.

ELM (E3SM Land Model) — Knowledge Infrastructure

Package: hydrocraft-elm-landsurface v1.0.0 Model: ELM (E3SM Land Model) — component of E3SM v3 Domain: Land surface processes (energy, water, carbon, nitrogen, phosphorus) Created by: Auto-dissection pipeline Last updated: 2026-03-26 Stats: 4 tools | 7 skill documents | 20 diagnostic triplets | ~1,800 lines of validated Python Validation status: documentation_validated (no HPC cluster available for execution)

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.

1. Overview

ELM (E3SM Land Model) is the land surface component of the Energy Exascale Earth System Model (E3SM), developed by the U.S. Department of Energy. It is a descendant of the Community Land Model (CLM) and simulates the exchange of energy, water, carbon, nitrogen, and phosphorus between the land surface and the atmosphere.

Key capabilities

• Biogeophysics: Radiative transfer (two-stream), surface energy balance, turbulent fluxes (Monin-Obukhov), soil thermal diffusion (20-layer), snow physics (12-layer SNICAR), lake thermodynamics (10-layer).
• Hydrology: Canopy interception, infiltration, Richards equation soil water, subsurface drainage, surface runoff (TOPMODEL/VIC), groundwater.
• Biogeochemistry: C/N/P cycling with prognostic phenology, litter decomposition (Century cascade), methane production/oxidation, nitrification/ denitrification, fire disturbance.
• Vegetation dynamics: Optional FATES (Functionally Assembled Terrestrial Ecosystem Simulator) for cohort-based vegetation.
• Crop model: Prognostic crop model with irrigation, fertilization.
• Urban model: CLMU urban canyon energy balance.

What makes ELM different from other land models

Domain scope

ELM is designed for global simulations on DOE supercomputers. Running it on a standalone workstation requires the full E3SM/CIME infrastructure. It cannot be run as a simple command-line executable — it requires case creation, namelist generation, compilation, and batch submission through the CIME framework.

2. Installation

Prerequisites

ELM requires the full E3SM software stack:

• HPC environment: MPI implementation (mpich or openmpi)
• Compilers: Fortran 2003+ (gfortran 9+, Intel ifort 19+, or NVHPC)
• Build tools: CMake 3.18+, GNU Make
• Libraries: NetCDF-Fortran, HDF5, PIO/SCORPIO (parallel I/O)
• CIME: Common Infrastructure for Modeling the Earth (included in E3SM)
• Python: 3.7+ (for CIME scripts, namelist generation)

Supported machines

ELM is designed for DOE Leadership Computing Facilities. Supported machines are listed in cime_config/machines/config_machines.xml. Running on unsupported machines requires creating a custom machine configuration.

# Check supported machines
cd /path/to/E3SM/cime/scripts
./query_config --machines

Build procedure (on a supported machine)

# 1. Clone and initialize submodules
git clone --recursive https://github.com/E3SM-Project/E3SM.git
cd E3SM
git submodule update --init --recursive --depth=1

# 2. Create a land-only case
cd cime/scripts
./create_newcase --case ../../my_elm_case \
    --compset I1850CNPRDCTCBCTOP \
    --res ne4pg2_ne4pg2 \
    --mach <MACHINE_NAME>

# 3. Setup and build
cd ../../my_elm_case
./case.setup
./case.build     # ~10-30 min depending on machine

# 4. Submit
./case.submit

Python tools dependencies (for this KI package)

pip install numpy pandas netCDF4 xarray matplotlib pyyaml

3. Pipeline Stages

The ELM simulation pipeline consists of 8 stages:

Parallelism

• Stages s1 and s2 can run in parallel (independent data preparation)
• Stages s3 and s4 can run in parallel (both depend on s1)
• Stage s5 depends on s0, s3
• Stage s6 depends on s1, s2, s4, s5

4. Tools Reference

5. Input Data Requirements

Atmospheric forcing (DATM)

ELM receives forcing from a data atmosphere model (DATM) that reads NetCDF files.

Surface dataset (surfdata_*.nc)

Created by mksurfdata_map tool or our convert_surface_data.py:

Parameter file (clm_params_*.nc)

Contains ~500 PFT-level and global parameters:

6. Output Description

ELM writes history files in NetCDF format. Up to 6 independent output streams (history tapes) can be configured with different variables and frequencies.

This section restates dag.yaml. The dag is the model identity for observable outputs; if this section and dag.yaml ever disagree, dag.yaml wins.

Headline output

QRUNOFF — Total runoff (surface runoff plus sub-surface drainage) leaving the land column. (mm/s)

DAG output inventory

Key output variables

History file configuration (in user_nl_elm)

! Daily output of water/energy variables
hist_nhtfrq(2) = -24
hist_mfilt(2) = 365
hist_fincl2 = 'GPP','NPP','QRUNOFF','FSH','EFLX_LH_TOT','H2OSOI','TSOI'

! Hourly output for a short period
hist_nhtfrq(3) = -1
hist_mfilt(3) = 8760
hist_fincl3 = 'FSA','FLDS','FSDS','RAIN','SNOW'

7. Namelist Configuration

ELM is configured through Fortran namelists in the lnd_in file, generated by CIME's build-namelist utility. Key namelist groups:

&elm_inparm (primary)

&elm_inparm
  ! Time stepping
  dtime = 1800                    ! Model timestep (seconds) — dt_005

  ! CO2
  co2_type = 'constant'          ! 'constant', 'diagnostic', 'prognostic'
  co2_ppmv = 284.7               ! CO2 concentration for 1850

  ! BGC mode
  bgc_mode = 'bgc'               ! 'sp' (satellite phenology), 'cn', 'bgc'
  use_cn = .true.                 ! Carbon-nitrogen cycling
  use_crop = .false.              ! Crop model
  irrigate = .false.              ! Irrigation

  ! Input files
  fsurdat = '/path/to/surfdata.nc'
  finidat = '/path/to/finidat.nc'   ! '' for cold start
  paramfile = '/path/to/clm_params.nc'

  ! Soil decomposition
  soil_decomp = 'ctc'            ! 'ctc' (Century) or 'cn' (CLM-CN)

  ! Hydrology
  h2osfcflag = 1                 ! Surface water scheme (0 or 1)
  origflag = 0                   ! Original CLM4 hydrology (0=off, 1=on)

  ! Nutrient competition
  nu_com = 'RD'                  ! 'RD' (relative demand), 'ECA', 'MIC'

  ! History
  hist_nhtfrq = 0, -24, 0, 0, 0, 0    ! 0=monthly, -N=every N hours
  hist_mfilt = 12, 365, 1, 1, 1, 1    ! Max time samples per file
/

8. Unit Conversion Table and Critical Domain Knowledge

Exact I/O shapes live in docs/format_spec.yaml; this table summarizes the unit conversions and unit-preservation rules called out by this KI.

Unit table

Critical domain knowledge — unit trap table

These are the most common silent errors when setting up ELM. Each entry links to a diagnostic triplet for automated detection.

9. Compset Reference

ELM compsets define the model configuration. Land-only compsets use DATM.

10. Vertical Structure

ELM uses a multi-layer vertical discretization:

Soil layers (default 20 hydrologically active)

Additional 15 thermal-only layers extend to ~40 m depth for deep soil temperature (important for permafrost simulations).

Snow layers (up to 12)

Snow is modeled with dynamic layering — layers are added/removed as snow accumulates/melts. Each layer tracks:

• Temperature (K)
• Liquid water content (kg/m²)
• Ice content (kg/m²)
• Grain size (µm) for SNICAR albedo

Lake layers (10)

For lake grid cells, a 10-layer lake model computes:

• Temperature profile
• Ice cover fraction
• Mixing (wind-driven, convective)

11. Validated Results

This KI is marked documentation_validated because no HPC cluster was available for execution. No achieved calibration or validation metric is claimed here. Judgment of any future run should use docs/validation_convention.yaml, restated below from the KI's convention facts.

Performance metrics — judged against the field's bar, not intuition

Data replacement tracking

12. Key Physical Constants

13. Coupling Points with Other Models

ELM exchanges fields with other E3SM components through the MCT coupler:

14. Diagnostic Triplets Summary

20 triplets covering 6 failure domains:

15. Quick Start (on a supported machine)

# 1. Clone E3SM
git clone --recursive https://github.com/E3SM-Project/E3SM.git
cd E3SM

# 2. Create a land-only case with satellite phenology (fastest)
cd cime/scripts
./create_newcase --case ../../elm_test \
    --compset IELM \
    --res ne4pg2_ne4pg2 \
    --mach <YOUR_MACHINE>

# 3. Configure
cd ../../elm_test
./case.setup

# 4. Customize namelist (optional)
cat >> user_nl_elm << 'EOF'
hist_nhtfrq = 0
hist_mfilt = 12
hist_fincl1 = 'GPP','NPP','QRUNOFF','FSH','EFLX_LH_TOT'
EOF

# 5. Build
./case.build

# 6. Submit
./case.submit

# 7. Monitor
tail -f CaseStatus

# 8. Find output
./xmlquery DOUT_S_ROOT
ls $(./xmlquery --value DOUT_S_ROOT)/lnd/hist/

16. File Structure

ki/
├── SKILL.md                           # This file — agent entry point
├── knowledge_infrastructure.yaml      # Schema-compliant package definition
├── tools/
│   ├── convert_forcing_to_elm.py      # s2: Atmospheric forcing converter
│   ├── convert_surface_data.py        # s1: Surface/soil data converter
│   ├── run_elm.py                     # s6: Execution wrapper
│   └── parse_elm_output.py            # s7: Output NetCDF → CSV parser
├── docs/
│   ├── s0_configuration.md            # Environment and installation
│   ├── s1_surface_data.md             # Surface dataset preparation
│   ├── s2_forcing_data.md             # Atmospheric forcing preparation
│   ├── s3_namelist_setup.md           # Namelist configuration
│   ├── s4_initial_conditions.md       # Initial conditions and spin-up
│   ├── s6_execution.md               # Running the model
│   └── s7_output_analysis.md          # Analyzing model output
├── diagnostics/
│   └── triplets.yaml                  # 20 symptom→diagnosis→remedy entries
└── workflow/
    └── workflow.md                    # Pipeline workflow description